JohnBabich/SomeIdeas

 = Some Ideas on Improving the Fedora Docs Workflow =
 * 1) !html
 * 1) !html

Introduction
This a collection of ideas currently being considered to improve the publication of official Fedora publications. Most of these ideas have been raised by other team members. I am collecting them together in one place so that we as a team can review and refine the workflow process.

New ideas, suggestions, tools and techniques are welcome.

Fedora Docs Team - Please fix any inaccuracies in this section.

1. MoinMoin Wiki - to jointly revise documents online
The Fedora Project is using this approach to produce the release notes. See The Release Notes Process. We have publicly been complimented on the quality of this work.

Currently, we are experimenting with updating the "Software Management Guide" in a similar manner. Once the wiki entries are finalized, the guides are converted into Doc Book XML.

2. Plone Content Management System (CMS) - for a more polished look
We can use the Plone application for static pages and a more polished look. Of course, we need to decide what exactly is "static" versus "dynamic". It has been proposed that the "index.html" or equivalent be static, with dynamic updating going on in Drafts. Once a document is finalized, it can be "static" in Plone and the team can jointly edit the new version in MoinMoin.

ADVANTAGES: More polished presentation, improvements in document maintenance.

DISADVANTAGES: learning curve in supporting a new platform.

3. Emacs and DocBook XML - for greater flexibility
We can use Emacs and Doc Script, print, etc.)

SOME INNOVATIVE APPROACHES TO CONSIDER
This section will cover new approaches as we collectively discover and/or devise them.

SARMA
For example, the GNOME team is working on Sarma, an online editor with DocBook XML import and export support. CVS commits are handled automatically. see http://live.gnome.org/LiveDocumentationEditing for further details.

This is in contrast to our current approach, which requires knowledge of Emacs, Doc Shot] )

4. Cross-stream collaboration, working with documentation teams from other projects (such as other dstributions and upstream projects) to create or contribute to a documentation commons.

5. Offline editing, such as using Gedit with the "Tag Lines" plugin. Any popular editor can also be used, as long as tagline features exist or can be easily added.

THE DOCUMENTATION WORKFLOW CYCLE
Note: The following documentation workflow is inspired by comments by Paolo Borelli, which appear on the aforementioned GNOME Sarma project page, http://live.gnome.org/LiveDocumentationEditing. Discussions with Karsten Wade and Paul W. Frields also heavily contributed to this concept. It's included here as a discussion point. (The artwork is mine) - JohnBabich



The four stages in the Documentation Workflow Cycle (Patent Pending - Not!) are:


 * Static content, posted on website, generated automatically from CVS or equivalent. This function could be enhanced by Plone in our scenario.


 * Distributive editing, where writer edits documentation online wiki-style or offline with tagline-capable editor. The writer gets task assignment through Bugzilla. Material edited offline is reposted to the wiki for review and/or further revision by team members.


 * Editorial review, wiki content reviewed by editors, before it is checked into CVS. Editorial functions include document version tracking, selection of best material from multiple versions, spell checking, and conversion of text to Doc Book conversion may be done manually or automatically.


 * Persistent storage, edited Doc Moin Wiki

Writing using the Wiki


 * Plone Test Site for the Fedora Project

http://fpserv.fedoraproject.org/


 * The Definitive Guide to Plone

http://plone.org/documentation/manual/definitive-guide


 * Current Issues with PDF Conversion

About PDF Conversion