From Fedora Project Wiki

m (1 revision(s))
(fixing markup)
Line 1: Line 1:
{{:DocsProject/Header}}
 
 
= Documentation Project Workflow =
 
= Documentation Project Workflow =
 
 
  
 
{{Anchor|ReleaseNotes}}
 
{{Anchor|ReleaseNotes}}
Line 13: Line 10:
 
== Wiki - Writing/Drafting ==
 
== Wiki - Writing/Drafting ==
  
1. Read [[DocsProject/WritingUsingTheWiki| DocsProject/WritingUsingTheWiki]]  tells how to structure a document on the Wiki for portability
+
# Read [[DocsProject/WritingUsingTheWiki| DocsProject/WritingUsingTheWiki]]  tells how to structure a document on the Wiki for portability
1. Know the rules for [[WikiEditing| WikiEditing]] , and especially the [[WikiEditing#Marking_Technical_Terms| markup rules]]  
+
# Know the rules for [[WikiEditing| WikiEditing]] , and especially the [[WikiEditing#Marking_Technical_Terms| markup rules]]  
1. Use the [[DocsProject/WritingDraftDocs| writing draft documents]]  page as a reference
+
# Use the [[DocsProject/WritingDraftDocs| writing draft documents]]  page as a reference
1. Read and understand the [[DocsProject/StyleGuide| style guidelines]]  
+
# Read and understand the [[DocsProject/StyleGuide| style guidelines]]  
  
 
{{Anchor|WikiPublicationMethodforFormalDocumentation}}
 
{{Anchor|WikiPublicationMethodforFormalDocumentation}}
 
== Wiki - Publication Method for Formal Documentation ==
 
== Wiki - Publication Method for Formal Documentation ==
  
1. Content is created, worked, and edited for approval in Docs/Drafts/Foo<code></code>Guide as per the flow in [[WikiWritingDrafting|  Wiki - Writing/Drafting]] .
+
# Content is created, worked, and edited for approval in Docs/Drafts/Foo<code></code>Guide as per the flow in [[WikiWritingDrafting|  Wiki - Writing/Drafting]] .
* Editor must be a different person than the writer(s)
+
#* Editor must be a different person than the writer(s)
1. Publication editor finalizes, copies to Docs/Foo<code></code>Guide.
+
# Publication editor finalizes, copies to Docs/Foo<code></code>Guide.
1. Writing team creates Docs/Drafts/<Fedora Ver Num>/Foo<code></code>Guide to work on branch drafts.
+
# Writing team creates Docs/Drafts/<Fedora Ver Num>/Foo<code></code>Guide to work on branch drafts.
1. Wiki is edited live before conversion to DocBook
+
# Wiki is edited live before conversion to DocBook
1. Conversion is conducted as per [[WikitoDocBookXML|  Wiki to DocBook XML]]  
+
# Conversion is conducted as per [[WikitoDocBookXML|  Wiki to DocBook XML]]  
1. Work for next release continues in Docs/Drafts/.
+
# Work for next release continues in Docs/Drafts/.
1. Request peer review and editing on list.
+
# Request peer review and editing on list.
  
 
{{Anchor|WikitoDocBookXML}}
 
{{Anchor|WikitoDocBookXML}}
Line 34: Line 31:
 
== Wiki to DocBook XML ==
 
== Wiki to DocBook XML ==
  
1. Document has completed steps in [[WikiPublicationMethodforFormalDocumentation|  Wiki - Publication Method for Formal Documentation]]  
+
# Document has completed steps in [[WikiPublicationMethodforFormalDocumentation|  Wiki - Publication Method for Formal Documentation]]  
1. Edit document to confirm it matches:
+
# Edit document to confirm it matches:
* http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki
+
#* http://fedoraproject.org/wiki/DocsProject/WritingUsingTheWiki
* http://fedoraproject.org/wiki/WikiEditing#Linking
+
#* http://fedoraproject.org/wiki/WikiEditing#Linking
* http://fedoraproject.org/wiki/WikiEditing#Lists and http://fedoraproject.org/wiki/DocsProject/StyleGuide/QuickReference#Lists
+
#* http://fedoraproject.org/wiki/WikiEditing#Lists and http://fedoraproject.org/wiki/DocsProject/StyleGuide/QuickReference#Lists
* http://fedoraproject.org/wiki/WikiEditing#Tables
+
#* http://fedoraproject.org/wiki/WikiEditing#Tables
* http://fedoraproject.org/wiki/WikiEditing#Notes,_Tips,_and_Other_Admonitions
+
#* http://fedoraproject.org/wiki/WikiEditing#Notes,_Tips,_and_Other_Admonitions
* http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms
+
#* http://fedoraproject.org/wiki/WikiEditing#Marking_Technical_Terms
* http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
+
#* http://fedoraproject.org/wiki/WikiEditing#Writing_Example_Commands
* http://fedoraproject.org/wiki/DocsProject/StyleGuide
+
#* http://fedoraproject.org/wiki/DocsProject/StyleGuide
1. 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]] .
1. 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}}
 
== Wiki - Docs Project (e.g. DocsProject/*) Content ==
 
== Wiki - Docs Project (e.g. DocsProject/*) Content ==
  
1. Work live in DocsProject/* or in your User<code></code>Name/ structure
+
# Work live in DocsProject/* or in your User<code></code>Name/ structure
1. If working in private space, copy over content when ready
+
# 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.*.
 
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.*.
Line 64: Line 61:
 
To write for the magazine:
 
To write for the magazine:
  
1. Designate one or more content flows or pieces of content as being under the vanilla [http://opencontent.org/openpub/ OPL] .
+
# Designate one or more content flows or pieces of content as being under the vanilla [http://opencontent.org/openpub/ OPL] .
1. All new submissions must have the standard [http://opencontent.org/openpub/ OPL]  reference at the end of the article.
+
# All new submissions must have the standard [http://opencontent.org/openpub/ OPL]  reference at the end of the article.
1. 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.
+
# 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.
1. 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:
+
# 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.
+
#* '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. :)
+
#* '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. :)
1. 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]] .
+
# 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}}
Line 76: Line 73:
 
== Full Process Flow, AKA 'From Idea to Document' ==
 
== Full Process Flow, AKA 'From Idea to Document' ==
  
1. A writer posts to [http://www.redhat.com/mailman/listinfo/fedora-docs-list/ fedora-docs-list]  with an idea or document, and the willingness to maintain it.
+
# A writer posts to [http://www.redhat.com/mailman/listinfo/fedora-docs-list/ fedora-docs-list]  with an idea or document, and the willingness to maintain it.
* New contributors should make a [[DocsProject/SelfIntroduction| SelfIntroduction]]  and read [[DocsProject/NewWriters| DocsProject/NewWriters]] .
+
#* New contributors should make a [[DocsProject/SelfIntroduction| SelfIntroduction]]  and read [[DocsProject/NewWriters| DocsProject/NewWriters]] .
1. 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| DocsProject/EditorAssignments]]  Wiki page.
+
# 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| DocsProject/EditorAssignments]]  Wiki page.
1. The writer produces an initial draft and submits it to [http://www.redhat.com/mailman/listinfo/fedora-docs-list/ 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.
+
# The writer produces an initial draft and submits it to [http://www.redhat.com/mailman/listinfo/fedora-docs-list/ 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.
* If the draft is Wiki-based, it should be in [[Docs/Drafts/| Docs/Drafts/]] .
+
#* If the draft is Wiki-based, it should be in [[Docs/Drafts/| Docs/Drafts/]] .
* If the draft is XML-based, it needs a new module in CVS; base the draft on the template in <code>example-tutorial</code> 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.
+
#* If the draft is XML-based, it needs a new module in CVS; base the draft on the template in <code>example-tutorial</code> 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.
* In the future, drafts may also be submitted through Plone (CMS) in XHTML or other acceptable formats.
+
#* In the future, drafts may also be submitted through Plone (CMS) in XHTML or other acceptable formats.
1. 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.
+
# 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.
1. 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.
+
# 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.
1. The assigned editor notifies the assigned manager when the document is ready for final review for publication.
+
# The assigned editor notifies the assigned manager when the document is ready for final review for publication.
1. Once the writer, editor, and manager agree that the document is complete, it is published on [http://docs.fedoraproject.org/ the official Documentation Website] .
+
# Once the writer, editor, and manager agree that the document is complete, it is published on [http://docs.fedoraproject.org/ 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<code></code>Book XML as required in the Documentation Guide.  In this way, the writer and the editor form a team with a mentorship aspect, so that the writer learns Doc<code></code>Book XML markup (and hopefully style as well) for more effective document maintenance later.
 
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<code></code>Book XML as required in the Documentation Guide.  In this way, the writer and the editor form a team with a mentorship aspect, so that the writer learns Doc<code></code>Book XML markup (and hopefully style as well) for more effective document maintenance later.
Line 118: Line 115:
 
== Getting a Document Translated ==
 
== Getting a Document Translated ==
  
1. Author or convert guide to XML
+
# Author or convert guide to XML
1. Use XML toolchain to generate the PO file (<code>make po</code>)
+
# Use XML toolchain to generate the PO file (<code>make po</code>)
1. Refer to fedora-docs-list for latest process to get PO files into [[L10n| L10n channels]] .
+
# Refer to fedora-docs-list for latest process to get PO files into [[L10n| L10n channels]] .
  
 
== Orphaning Documents ==
 
== Orphaning Documents ==

Revision as of 11:56, 26 May 2008

Documentation Project Workflow

Release Notes

DocsProject/ReleaseNotes/Process,, from="^

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/FooGuide as per the flow in Wiki - Writing/Drafting .
    • Editor must be a different person than the writer(s)
  2. Publication editor finalizes, copies to Docs/FooGuide.
  3. Writing team creates Docs/Drafts/<Fedora Ver Num>/FooGuide to work on branch drafts.
  4. Wiki is edited live before conversion to DocBook
  5. Conversion is conducted as per Wiki to DocBook XML
  6. Work for next release continues in Docs/Drafts/.
  7. Request peer review and editing on list.

Wiki to DocBook XML

  1. Document has completed steps in Wiki - Publication Method for Formal Documentation
  2. Edit document to confirm it matches:
  3. Use native MoinMoin tools convert the document to XML and edit the resulting work for DocBook compliance and project norms, as per the wiki to XML conversion how-to .
  4. Follow [#Full_Process_Flow full steps for getting a CVS module] for a Docbook document.

Wiki - Docs Project (e.g. DocsProject/*) Content

  1. Work live in DocsProject/* or in your UserName/ structure
  2. 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.*.

Magazine

Project in limbo -- 2007-10-23 quaid@fedoraproject.org

For details, read DocsProject/Magazine .

To write for the magazine:

  1. Designate one or more content flows or pieces of content as being under the vanilla OPL .
  2. All new submissions must have the standard OPL reference at the end of the article.
  3. If you do not have one, sign up for an account on del.icio.us . The Firefox plug-in made by del.icio.us is highly recommended.
  4. After you have written a piece of content following the guidelines, view the page in Firefox and tag the page using 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 del.icio.us extension has tab-complete for tags, so you will only have to type it one time. :)
  5. 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 page, or even be the source of content for a new entry in the relnotes via Docs/Beats .

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. 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.
  3. 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.
    • If the draft is Wiki-based, it should be in Docs/Drafts/ .
    • If the draft is XML-based, it needs a new module in CVS; base the draft on the template in example-tutorial 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.
    • In the future, drafts may also be submitted through Plone (CMS) in XHTML or other acceptable formats.
  4. 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.
  5. 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.
  6. The assigned editor notifies the assigned manager when the document is ready for final review for publication.
  7. 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 DocBook XML as required in the Documentation Guide. In this way, the writer and the editor form a team with a mentorship aspect, so that the writer learns DocBook 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 OPL

Stop (medium size).png Canonical documents, such as the Documentation Guide, or other high-risk content areas are somewhat more closely controlled.

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

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 (make po)
  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.

Wiki-based Orphans

Empty, fill me

CVS-based Orphans

Empty, fill me

Plone-based Orphans

Empty, fill me

Further Considerations

Empty, fill me

WikiWorkflow