Archive:DocsProject/DocumentationGuide
From FedoraProject
These notes were created long, long ago and don't accurately reflect Docs Project work flow anymore. This document really should be abandoned completely.
Contents |
Fedora Documentation Guide
This is the canonical source for how the FDP process works -- in other words, how contributors work together to get documentation from ideas to publication. The Documentation Guide is just as much a work in progress as many other parts of Fedora, and we need your help to improve it -- especially if it didn't help you as much as we said it would!
The current release of the Documentation Guide is available at the following URL:
http://docs.fedoraproject.org/documentation-guide/
The FDP is currently planning the "next-generation" Documentation Guide, to wit:
Suggestions
If you have suggestions for the Documentation Guide , File a bug with this pre-filled bug report , or you can make notes here.
If you add to this list, please be fair to others and make your addition at the bottom of the list. If an addition is important, we'll try to reprioritize accordingly.
- A very short front chapter that serves as a "guide to the Guide."
- Introduce an example tutorial and tie to the CVS tree so people can learn while DOING
- An example within the guide itself, so the guide is a self-referential resource
- A specific raw-template that is in CVS to be checked-out, renamed, and written into.
- Gentler and more descriptive information for people who have no previous exposure to the tools we use.
- Incorporate information from the Quick Start Guide in more detail. We can make this an actual chapter, then link directly to it from the FDP project page in the same way we do now. Worth a reference to this Emacs quick reference of basic editing skills .
- A Style chapter (wait, I think I have just the thing...)!
- Add user instructions on installing xmlto and docbook files etc. via yum and apt, as per Duncan Lithgows' suggestion
- Incorporate document lifecycle section
- Incorporate the DocsProject/NewWriters checklist (we can then drop that page).
- Make sure CVS section includes info on .cvsignore for interested parties
- Include coding style guidelines, most likely within the example tutorial
- Include (or link to) a standard set of terms, to ensure that explanations are clear and consistent (simple ex.: a "system" is a single instance of an OS, and Xen magic means many "systems" on one "computer", which might not be a "PC").
- Include notes on writing good instructions, because there are many pitfalls ! Examples: remembering to tell the reader to adjust the system firewall when you tell them to enable a service, remembering that users should be in unprivileged sessions, so tasks that require root need an extra element (e.g. su -c 'command' for CLI commands).
- An observation: Info on navigating Bugzilla (as mentioned in Example Tutorial ) is useful to many non-regular contributors too - testers, patch submitters and people with suggestions would also benefit, as Bugzilla isn't the most friendly interface...
- I think we should move the DocBook Coverage in FDP Tools up a bit, to explain what DocBook actually is for the layman. Who uses it, like Cisco and every Open Source Project worth their salt ;-) etc.
- Under the CVS section, a tip about symlinking to the (new) docs-common/ directory in ./, for those who like that sort of thing. Note that the symlink cannot be committed to CVS.
- Standard "About This Document" section for all documents, as proposed at bug #139931
- CVS best practice to add -- when you are closing out a bugzilla report with the contents of a CVS commit, refer to the bug number in the CVS commit message and what status this commit brings the bug to (complete, needinfo, QA, etc.).
- CVS best practice #2 -- more commits can be better than fewer. This is especially important when making big changes, you don't want to bury and obscure changes by having too many of different types. When affecting bugs with a commit, it is generally a good idea to have one commit per each bug or group of bugs.
- CVS best practice #3 -- handle binary objects in a special way.
- Include process for work routines in FDP:
- Whiteboard projects on Wiki
- Convert each task into a bug report
- Make one or more master tracker bugs
- Use the dependency tree in bugzilla to track tasks
- Possibly incorporate anything useful from DocsProject/WritingDraftDocs
- Include information on OpenOffice.org DocBook support
- Specify no periods in titles/headings
- We intend for a stock Fedora installation to provide all the tools a user of the Doc Guide needs, although that might require pulling a group from Extras. To facilitate this, we need to keep from customizing e.g. Emacs (http://docs.fedoraproject.org/documentation-guide/s1-emacs-colors.html).
Documentation Guide v2 Outline
This is a working outline for the next generation Documentation Guide. It is sure to change often during the planning stage.
Note from the FDSCo meeting of 26 April 2005: It might make sense to check the organization of this outline against whom each chapter concerns. Perhaps an organizing factor based on roles works best. I.e. one <part> of the <book> primarily for writing, one <part> for editing, one <part> for process management (FDSCo), others?
I. "Guide to the Guide" A. Explain mission and purpose A. Talk about how to use the Guide 1. Separate by experience level 1. If you can't find info here A. Conventions (how to read the rendered markup in the Guide) A. Why there is a process A. How meritocracy works in FDP I. "Quick Start" A. What is the FDP 1. Mission 1. FDSCo
- Reproduce charter?
1. Parameters a. Fedora Core and Extras software only a. No non-free tools in toolchain A. Explain how to get involved 1. Join mailing list a. The first step in joining the Fedora Documentation Project is to join the community and engage in the discussion. Subscribe to the fedora-docs-list and fedora-announce-list to keep up to date and informed about the project and Fedora in general. The lists can be found at
- https://listman.redhat.com/mailman/listinfo/fedora-docs-list
- http://www.redhat.com/mailman/listinfo/fedora-announce-list
- https://www.redhat.com/mailman/listinfo/fedora-dsco-list
a. After visiting the pages and filling in the needed information an automated email message will be sent. Choose to follow the link or respond to the email as outlined in the instructions contained in the emails.
1. Install toolset (yum/Pirut)
a. Next, ensure that the proper tool set is installed. The first tools that should be installed are Yum and/or Pirut. These Software Management Utilities will ensure that all software packages are current and aid in installing those not already installed. Both are installed by default on Fedora Core 5 but this can be checked using rpm. Either package will work for managing software packages.
[user@user ~] $ rpm -qa pirut pirut-1.0.3-0.fc5 [user@user ~] $ rpm -qa yum yum-2.6.1-0.fc5
1. Setup PGP and Email a. After that, setup Privacy Guard Software and utilities to manage the Gpg keys. Use GPG to identify yourself and authenticate your communications, even with people you don't know. GPG allows anyone reading a GPG-signed email to verify its authorship. In other words, GPG allows someone to be reasonably certain that communications signed by you actually come from you. GPG is useful because it helps prevent mischievous third parties from polluting code or conversations by masquerading as other entities. To participate in any part of the Fedora Project,
- You should have a GPG key pair, and
- Your public key must be available on pgp.mit.edu, a well-known public keyserver.
a. Some Privacy Guard Software and Management Utilities include: I. GnuPG http://fedoraproject.org/wiki/Cryptography has a wonderful explanation on how to install openssh and GnuPG. I. Seahorse is a GUI utility to manage keys. Go to http://seahorse.sourceforge.net/ for information on installing and using this utility. I. KGpg is the KDE GPG key manager and can be installed via yum if not already installed. Information and instructions can be found at http://developer.kde.org/~kgpg/ a. After GnuPG is installed go to http://fedoraproject.org/wiki/DocsProject/UsingGpg/CreatingKeys and follow the instructions there to generate a GPG key pair. For additional information the Legacy site http://www.fedoraproject.org/wiki/Legacy/PGPHowTo has a lot of good information on key pair generation and use as well. It is also necessary to setup your email program to work with GnuPG so that signing and verification of emails is possible. Instructions for each can be found as follows: I. Evolution - A helpful page is located at http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithEvolution I. Thunderbird - Has help located here, http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithThunderbird I. Kmail - Located here, http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithKmail is still a work in progress and I. Pine - Located here, http://fedoraproject.org/wiki/DocsProject/UsingGpg/WithKmail is also a work in progress. 1. Create a Bugzilla account with Red Hat so that you can report bugs. a. Fill out subscription page located at https://bugzilla.redhat.com/bugzilla/index.cgi and select New Account. a. You will receive an email. Simply respond to or follow the link in the email to confirm you account and you are done. 1. Next create a Fedora Project Account. This is not the same as a Bugzilla Account. This is to work with and on the Fedora Project. a. Go to https://admin.fedora.redhat.com/accounts/ and apply for an account by filling out the Subscription page. You will then receive an email simply respond to or follow the link in the email to complete the Account setup. a. Request and complete a Contributor License Agreement(CLA) by going to the same page and requesting one via the link there. A (CLA) will be emailed to the account on file. Once received,follow the instructions in the email, fill it out, sign it with your GPG key and return it. You will then get a confirmation email. Then download and save the client-side certificate following the instructions on the same page. 1. That completes setting up all the needed accounts and ensuring that the proper tool chain is installed. There is one final step to the process. This one is not as hard. Post a self-introduction to the fedora-docs-list. Please let us know who you are, your name and a short summary of your background and qualifications. Next include some information on what you hope to achieve by joining the project or how you wish to contribute. Finally, please include you GPG Key and fingerprint ID. 1. Congratulations and welcome to the Fedora Documentation Project. This is the first step in what is hoped will be a rewarding and positive experience for you as well as for the community. I. Process/Document Lifecycle
A. Define roles and responsibilities 1. Writer 1. Editor 1. Manager A. Idea to Production A. Production to Publication A. Publication to Maintenance I. FDP Tools A. DocBook XML 1. Not a requirement for drafts, but for maintenance 1. Why you shouldn't fear DocBook XML A. CVS (This section will include the information from the CvsUsage and CvsHelp pages.) A. Bugzilla 1. How to get a Bugzilla account 1. Bugzilla guidelines? 1. Tracker bugs (http://www.redhat.com/archives/fedora-docs-list/2005-April/msg00324.html) 1. Dependency view A. Wiki 1. How to get a Wiki account 1. Wiki guidelines? 1. Task tracking on the schedule a. Tying to outlines a. Tying to Bugzilla (see above) A. IRC A. Outside channels 1. Private repositories 1. Email - minimize out of band if relevant I. Example Tutorial
- This will be a section that guides a user through the toolchain in a gentle fashion.
I. System Documenting Guidelines A. Eliminate all system and user customizations A. Use standard theme for screenshots A. Use of Xen/VMware? I. Other Writing Tools A. Emacs 1. psgmlx 1. nxml A. jEdit A. Conglomerate A. others... I. DocBook XML Guidelines (tags and formatting) A. Required entities 1. &FEDORA-ENTITIES-EN; 1. &BOOKID; 1. &LEGALNOTICE; 1. &BUG-NUM; (Bugzilla entry for document, tracker for other bugs) A. Required articleinfo 1. title 1. copyright 1. authorgroup a. author a. editor 1. &LEGALNOTICE; 1. revisioninfo A. Required logical structures 1. Introduction a. Purpose - define OBJECTIVES for the tutorial, not what you're writing about... What will the user be able to do when finished reading and understanding? a. Audience - do not define a group ("newbies," "admins"), define the skills required first a. About XXX - one or more, one for each major technology involved (this is not for "About This Document" -- that is what "Purpose" is for above) a. Additional Resources - include web sites, deadtree books, source material
- Always includes link to &FDPDOCS-URL; and &FDP-URL;
a. Acknowledgments - optional a. Applicable draft or other notices (specific &FCLOCALVER; for instance) 1. Use <section>, not <sectN> 1. Element naming guidelines I. Style Guidelines (grammar, usage, etc.) - Include information in the StyleToDo .
Gotchas
These will be included in the DocGuide guidance. This is a dumping ground for pet peeves, more or less. The DocGuide will avoid negative tone, of course. :-)
- Don't <indexterm> in section headers. <indexterm> only actual words (such as <firstterm>), phrases, or inside a <para> or such where a specific issue is worth indexing.
- Don't name files in CVS "fedora-*". It's in Fedora Docs CVS, so it's presumably about Fedora. Stop redundancy before it becomes redundant!
[FIXME: More to come!]
