From Fedora Project Wiki

(fixing markup)
 
(43 intermediate revisions by 7 users not shown)
Line 1: Line 1:
= Documentation Project Workflow =
{{needs love}}
{{header|docs}}
 
== 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 [https://fedoraproject.org/wiki/Category:Draft_documentation draft stage], documents are [https://fedoraproject.org/wiki/Writing_for_DocBook_using_the_wiki 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 [https://fedoraproject.org/wiki/Release_notes_wiki_to_XML_conversion_process converted into XML.]
 
Release notes, guides, and formal documents on a specific piece of software are published in [https://fedoraproject.org/wiki/DocBook_Editor DocBook XML.] Published XML documents are converted into html, pdf, and other formats [https://fedoraproject.org/wiki/Publishing_draft_documentation_using_Publican using Publican.]
 
Once in the XML format, the document is checked into a [https://fedoraproject.org/wiki/Branching_a_document_in_git git branch] where it may be further edited.
 
Finished product is available at [http://docs.fedoraproject.org docs.fp.o] and sometimes [https://fedoraproject.org/wiki/Package_Review_Process packaged] for the Fedora [http://koji.fedoraproject.org/koji/packages?tagID=108 repositories.]
 
<!-- <center>[[Image:{{{image|TLflow2.png}}}]]</center> -->
<center>[[Image:{{{image|TLflowLR.png}}}]]</center>
 
== Announcements ==
 
The Docs Project often works with [https://fedoraproject.org/wiki/Marketing marketing] to produce [https://fedoraproject.org/wiki/Final_announcement_SOP 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.
 
<!-- <center>[[Image:{{{image|flo-announce.png}}}]]</center> -->
<center>[[Image:{{{image|flo-announceLR.png}}}]]</center>


{{Anchor|ReleaseNotes}}
{{Anchor|Release_Notes}}
== Release Notes ==
== Release Notes ==


{{:DocsProject/ReleaseNotes/Process,, from="^## INCLUDERELNOTESPROCESSSTART$", to="^## INCLUDERELNOTESPROCESSEND$"}}
[https://fedoraproject.org/wiki/Category: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.
 
<!-- <center>[[Image:{{{image|flo-relnotes.png}}}]]</center> -->
<center>[[Image:{{{image|flo-relnotesLR.png}}}]]</center>
 
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 <u>typical</u>, Guides are sometimes packaged
and there is no reason input cannot be collected on the wiki.
 
<!-- <center>[[Image:{{{image|flo-guides.png}}}]]</center> -->
<center>[[Image:{{{image|flo-guidesLR.png}}}]]</center>
 
== 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 [https://admin.fedoraproject.org/accounts Fedora Access Account.] To become a member of '''Docs''', [https://fedoraproject.org/wiki/Join_the_Docs_Project 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 [https://fedoraproject.org/wiki/Docs_Project_guides_table 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.
 
<!-- <center>[[Image:{{{image|docs-permissions.png}}}]]</center> -->
<center>[[Image:{{{image|docs-permissionsLR.png}}}]]</center>
 
==Translations==
 
The following page details the translation process:
 
[[Docs_Project_workflow - translations]]
 
== Note: Source ==
 
The sources for the above images are text:
 
<!--* [[Docs_Workflow_TLflow2.dot]]
* [[Docs_Workflow_flo-announce.dot]]
* [[Docs_Workflow_flo-relnotes.dot]]
* [[Docs_Workflow_flo-guide.dot]]
* [[Docs_Workflow_docs-permissions.dot]]-->
* [[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|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.
 
= Old Material still to be incorporated =
 
{{admon/note| Out of date | Much of the material below is badly out of date or in need of considerable editing.  It has been commented out for now.}}
 
<!--


{{Anchor|WikiWritingDrafting}}
{{Anchor|WikiWritingDrafting}}
== Wiki - Writing/Drafting ==
== Wiki - Writing/Drafting ==


Line 33: Line 149:
# Document has completed steps in [[WikiPublicationMethodforFormalDocumentation|  Wiki - Publication Method for Formal Documentation]]  
# Document has completed steps in [[WikiPublicationMethodforFormalDocumentation|  Wiki - Publication Method for Formal Documentation]]  
# Edit document to confirm it matches:
# Edit document to confirm it matches:
#* http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki
#* [[DocsProject/WritingUsingTheWiki]]
#* http://fedoraproject.org/wiki/WikiEditing#Linking
#* [[WikiEditing#Linking]]
#* http://fedoraproject.org/wiki/WikiEditing#Lists and http://fedoraproject.org/wiki/DocsProject/StyleGuide/QuickReference#Lists
#* [[WikiEditing#Lists]] and [[DocsProject/StyleGuide/QuickReference#Lists]]
#* http://fedoraproject.org/wiki/WikiEditing#Tables
#* [[WikiEditing#Tables]]
#* http://fedoraproject.org/wiki/WikiEditing#Notes,_Tips,_and_Other_Admonitions
#* [[WikiEditing#Notes,_Tips,_and_Other_Admonitions]]
#* http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms
#* [[WikiEditing#Marking_Technical_Terms]]
#* http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
#* [[WikiEditing#Writing_Example_Commands]]
#* http://fedoraproject.org/wiki/DocsProject/StyleGuide
#* [[DocsProject/StyleGuide]]
# Use native MoinMoin tools convert the document to XML and edit the resulting work for DocBook compliance and project norms, as per the [[DocsProject/Wiki2XML| wiki to XML conversion how-to]] .
# Use native MoinMoin tools convert the document to XML and edit the resulting work for DocBook compliance and project norms, as per the [[DocsProject/Wiki2XML| wiki to XML conversion how-to]] .
# Follow [#Full_Process_Flow full steps for getting a CVS module]  for a Docbook document.
# Follow [[#Full_Process_Flow | full steps for getting a CVS module]]  for a Docbook document.


{{Anchor|WikiDocsProjectContent}}
{{Anchor|WikiDocsProjectContent}}
Line 51: Line 167:


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.*.
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.*.
{{Anchor|Magazine}}
== Magazine ==
''Project in limbo -- 2007-10-23 quaid@fedoraproject.org''
For details, read [[DocsProject/Magazine| DocsProject/Magazine]] .
To write for the magazine:
# Designate one or more content flows or pieces of content as being under the vanilla [http://opencontent.org/openpub/ OPL] .
# All new submissions must have the standard [http://opencontent.org/openpub/ OPL]  reference at the end of the article.
# If you do not have one, sign up for an account on [http://del.icio.us del.icio.us] .  The Firefox plug-in made by [http://del.icio.us del.icio.us]  is highly recommended.
# After you have written a piece of content following the guidelines, view the page in Firefox and tag the page using [http://del.icio.us del.icio.us] .  Amongst any other tags you wish, be sure to use:
#* 'for:fedoradocs' as one of the tags.
#* 'fedorabeats'  as another tag, if you are designating it as for the special content feed.  The [http://del.icio.us del.icio.us]  extension has tab-complete for tags, so you will only have to type it one time. :)
# Designated editors log in to the fedoradocs account and retag content suggestions that have arrived via the 'for:' tag.  Content may be designated as going into one or more feeds, be linked from a [[Docs/Beats| Docs/Beats]]  page, or even be the source of content for a new entry in the relnotes via [[Docs/Beats| Docs/Beats]] .


{{Anchor|FullProcessFlow}}
{{Anchor|FullProcessFlow}}
{{Anchor|Full_Process_Flow}}
{{Anchor|Full_Process_Flow}}
== Full Process Flow, AKA 'From Idea to Document' ==
== Full Process Flow, AKA 'From Idea to Document' ==


Line 97: Line 197:
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.
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 [[Legal/Licenses#Documentation| OPL]]  
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 [[Legal/Licenses#Documentation| CC-BY-SA]].


{{Template:Warning}} '''Canonical documents, such as the Documentation Guide, or other high-risk content areas are somewhat more closely controlled.'''
{{admon/important||Canonical documents, such as the Documentation Guide, or other high-risk content areas are somewhat more closely controlled.}}


== Other Projects ==
== 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 [fedora-docs-list@redhat.com] .
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] .


{{Anchor|XMLDocbookPublicationMethod}}
{{Anchor|XMLDocbookPublicationMethod}}
Line 123: Line 223:
Refer to [[#Full_Process_Flow| Full Process Flow]]  for a complete explanation.
Refer to [[#Full_Process_Flow| Full Process Flow]]  for a complete explanation.


=== Wiki-based Orphans ===
-->
 
''Empty, fill me''
 
=== CVS-based Orphans ===
 
''Empty, fill me''
 
=== Plone-based Orphans ===
 
''Empty, fill me''
 
== Further Considerations ==
 
''Empty, fill me''


WikiWorkflow
[[Category:Docs Project process]]

Latest revision as of 20:02, 27 October 2010

This page needs some love
This page should be revised or reconstructed to be more helpful. Problems may include being out of step with current team or project status or process.

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:

  • [2] - Wiki review
  • [4] - Managing the document in git
  • [5] - Reviewing/Editing the XML Document
  • [6] - Building a document from git
  • [7] - Packaging a Publican document

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:

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.

Old Material still to be incorporated

Out of date
Much of the material below is badly out of date or in need of considerable editing. It has been commented out for now.
Retrieved from "https://fedoraproject.org/w/index.php?title=Docs_Project_workflow&oldid=204329"