Line 44: | Line 44: | ||
* '''[3]''' - [[Converting wiki to DocBook XML]] | * '''[3]''' - [[Converting wiki to DocBook XML]] | ||
* '''[8]''' - [[Publishing a document with Publican]] | |||
== Guides == | == Guides == |
Revision as of 12:52, 26 August 2010
Docs Projects
The mission of the Fedora Documentation Project is to provide documentation to users and developers to improve the overall usage of Fedora. We do that by explaining the usage of certain pieces of software or systems, provide written accounts of special events (releases, etc), and provide recommendations on setting of software or systems (security, performance, etc).
While in draft stage, documents are produced on the wiki. There material from various subject matter experts is collected. If the author prefers, a document may be written offline. No matter how the document is drafted, it will always be converted into XML.
Release notes, guides, and formal documents on a specific piece of software are published in DocBook XML. Published XML documents are converted into html, pdf, and other formats using Publican.
Once in the XML format, the document is checked into a git branch where it may be further edited.
Finished product is available at docs.fp.o and sometimes packaged for the Fedora repositories.
Announcements
The Docs Project often works with marketing to produce announcements. This work tends to be done almost entirely within the wiki, and rarely, if ever is a formal document produced. Occasionally, the Fedora Design Team will take the wiki document and use it as the basis for a glossy document or brochure. A similar process, obviously without the engagement of Marketing, is used when documenting Docs Project procedures or policies.
Release Notes
Release notes, on the other hand, almost always follow the complete process. The only unfrequented path is directly writing to DocBook; Release Notes are always developed in the wiki first.
Step details:
Guides
Guides are typically not developed in the wiki but rather written straight to DocBook. In addition, Guides are typically not packaged. The emphasis here is on typical, Guides are sometimes packaged and there is no reason input cannot be collected on the wiki.
Access Control
The Fedora Docs Project has three access groups for contributors: Docs, Doc-Writers, and Doc-Publishers.
1. Members of Docs are part of the Fedora Docs Project as voting contributors. They get write access to the wiki, as does everyone with a Fedora Access Account. To become a member of Docs, Join the Docs Project and you will be 'sponsored' by someone in the The Fedora Docs Project leadership. Then you may work on writing projects on the wiki or 'garden' existing pages.
2. Members of Doc-Writers are part of the Fedora Docs as voting contributors who have a document to commit and maintain in the git repository. Each guide is managed in various repositories by members of this group. Promotion from Docs to Doc-Writers requires application on FAS and a sponsor. Contributors who have learned to write XML and become familiar with git are entered into the Docs writers group, allowing access to the git repositories. Each document is maintained in a git repository, and the writer group grants access to all of these.
3. Members of Doc-Publishers are part of the Fedora Docs as voting contributors who have a document to commit and maintain in the docs.fp.o hich permits committing changes to the
Fedora documentation website. Promotion from Docs to Doc-Publishers requires application on FAS and a sponsor.
Other: If a contributor needs to package a document, the packaged document is submitted for review, and once successfully reviewed, the contributor gets packager privilege, and may push that package to the Fedora repositories.
Note: Source
The sources for the above images are text:
- Docs_Workflow_TLflowLR.dot
- Docs_Workflow_flo-announceLR.dot
- Docs_Workflow_flo-relnotesLR.dot
- Docs_Workflow_flo-guideLR.dot
- Docs_Workflow_docs-permissionsLR.dot
If you wish to edit the above images, install the graphiz
package and save the text on one of the above pages to a text file. Then execute the command:
dot -Tpng -o TLflow2.png TLflow2.dot
(or whichever file you select). Edit the source and repeat until the image is how you desire. Note that the various flow- files are copies of TLflow2 with various sections grayed and the size reduced. Then update the source wiki page for those following you, and upload the png to the wiki. Refresh this page and be sure it appears in context correctly.