Docs Project workflow

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:


 * [1] - Docs Project workflow - beat writing


 * [2] - Wiki review


 * [3] - Converting wiki to DocBook XML


 * [4] - Managing the document in git


 * [5] - Reviewing/Editing the XML Document


 * [6] - Building a document from git


 * [7] - Packaging a Publican document


 * [8] - Publishing a document with Publican


 * [9] - Getting the release notes to Bodhi


 * [10] - Giving_a_document_karma

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.



Translations
The following page details the translation process:

Docs_Project_workflow - translations

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 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.

= Old Material still to be incorporated =

<!--

Wiki - Writing/Drafting

 * 1) Read  DocsProject/WritingUsingTheWiki  tells how to structure a document on the Wiki for portability
 * 2) Know the rules for  WikiEditing, and especially the  markup rules
 * 3) Use the  writing draft documents  page as a reference
 * 4) Read and understand the  style guidelines

Wiki - Publication Method for Formal Documentation

 * 1) Content is created, worked, and edited for approval in Docs/Drafts/Foo Guide.
 * 2) Writing team creates Docs/Drafts//Foo Name/ structure
 * 3) If working in private space, copy over content when ready

There is not much formal process around this. Projects handle this internally, and we trust our own project members to do The Right Thing. Of course, all project members should be watching each other by subscribing to Docs.*.

Full Process Flow, AKA 'From Idea to Document'

 * 1)  A writer posts to fedora-docs-list  with an idea or document, and the willingness to maintain it.
 * 2) * New contributors should make a SelfIntroduction  and read  DocsProject/NewWriters.
 * 3)  If the consensus of the list is that the proposal is feasible, then the writer is assigned an editor and the proposal is registered on the the  DocsProject/EditorAssignments  Wiki page.
 * 4)  The writer produces an initial draft and submits it to fedora-docs-list .  The writer directs any queries or questions either to the mailing list or to the assigned editor.  The FDP encourages writers to participate on the mailing list, which is an active forum for help and debate.
 * 5) * If the draft is Wiki-based, it should be in Docs/Drafts/.
 * 6) * If the draft is XML-based, it needs a new module in CVS; base the draft on the template in  and write to the list when it is ready, so that a CVS admin can respond.  Making a module includes creating a bugzilla component for it.
 * 7) * In the future, drafts may also be submitted through Plone (CMS) in XHTML or other acceptable formats.
 * 8)  A manager with access-granting privilege creates a container in CVS for the document in progress, and gives the writer CVS access.  The assigned manager can assist the writer and editor in ensuring that the document is compatible with the technical requirements of Fedora.
 * 9)  The editor negotiates any work schedule with the writer if necessary.  Both may commit revisions during the editorial process, subject to the FDP document lifecycle guidance.
 * 10)  The assigned editor notifies the assigned manager when the document is ready for final review for publication.
 * 11)  Once the writer, editor, and manager agree that the document is complete, it is published on the official Documentation Website.

This process promotes an extremely low barrier to entry. The writer's work may be in any format desired (including plain text) up to the point of final markup, as agreed upon by the editor. The final markup will be in Doc Book XML markup (and hopefully style as well) for more effective document maintenance later.

The Wiki is used as either an interim drafting tool or as a final publishing location. The Wiki is good for very short, one-page how-to pieces, but is not used for maintaining full-length tutorials or guides. If you want to author in the Wiki, you need to use the rules at WikiEditing  and  WritingUsingTheWiki.

Writers may gain access to additional document containers by providing substantial improvements to those documents in association with their writers, editors, and managers. The definition of substantial is left to the editors and managers for each document, to provide maximum fluidity. Regular contributors may be added to a list of "power writers/editors" with access to all other containers.

Withdrawing a Proposed Document
A writer may email their editor and withdraw proposals or documents in progress without any prejudice. The FDP recognizes that sometimes changing circumstances result in work delays or cancellations, through no fault of the writer. It is far better to cancel than to just drop the work or disappear. The first shows maturity as a contributor, the second and third make people not willing to trust you in the future.

Fedora is a dynamic project that aims for both open participation and high standards. For these reasons, editors and managers may ask writers to amend their drafts before accepting them. If the writer does not respond, or no agreement can be reached, then the editor may request that the proposal or documents in progress be withdrawn.

The FDSCo must be made aware of withdrawals. Once a withdrawal is known, the editor then moves to close the bug component and informs the writer by email. Once a proposal or document in progress has been withdrawn, other writers may submit their own proposals for the same subject. Naturally, anyone is welcome to use the in-progress work and continue with it, as long as the work has been correctly contributed to the project and is therefore under the CC-BY-SA.

Other Projects
Other projects are welcome to use these methodologies/workflows. Any that wish to have their documentation be formally part of the FDP set should contact [docs@lists.fedoraproject.org].

XML - DocBook Publication Method
EditingFedoraRedhatCom

http://fedoraproject.org/wiki/DocsProject/Tasks

Getting a Document Translated

 * 1) Author or convert guide to XML
 * 2) Use XML toolchain to generate the PO file
 * 3) Refer to fedora-docs-list for latest process to get PO files into  L10n channels.

Orphaning Documents
Refer to Full Process Flow  for a complete explanation.

-->