JohnBabich/SomeIdeas

#!html
<font size="+1">

Some Ideas on Improving the Fedora Docs Workflow

#!html
</font>

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

ADVANTAGES: Ease-of-use, low barrier to entry.

DISADVANTAGES: No automatic tracking of cross-references, no completely automated conversion to DocBook 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 DocBook XML to publish our efforts in any desired format: web pages, PDFs, Postscript, etc. The advantage of this is the "write once, use often" approach, which is a primary tenet of modular programming and the basis of FLOSS. These documents are also the base for the many translations which are produced by our Translation team members.

ADVANTAGES: Automatic tracking of cross-references, version tracking, standard "code" base.

DISADVANTAGES: Steep learning curve for non-FLOSS coders and non-coders in general.

THE CHALLENGES RESULTING FROM THIS APPROACH

There are definite disadvantages to this three-pronged approach. It would be great if we could do everything with one tool - maybe someday soon we will. For now, we can enjoy the advantages this approach offers. Now here are the obstacles, which are best seen as challenges.

1. Complexity.

Multiple tools are harder to use than one tool. Most of us know one tool really well, some of us know two tools pretty well, and a few know all the tools (of whom we stand in awe). There is also the issue of conversion from one format to the other.

This is why the team approach (the bazaar) is so powerful. As a community, we are stronger than as individuals. We can pool our expertise and produce a whole greater than the sum of its parts. We also have powerful FLOSS tools from which to draw.

SOLUTION: Teamwork, teamwork, teamwork and tools, tools, tools

2. Coordination of Effort.

This is always a challenge. Many times "we have a failure to communicate". The good news is we have great tools at our disposal: wikis, email, IRC channels, etc. People are making good money promoting "collaboration". We have the tools we need already at hand - we just have to make use of them. New tools are emerging like VoIP.

SOLUTION: Explain to contributors the best ways to communicate. One great guide is Communicating and Getting Help

3. Multilingual Teams.

This is a challenge that arises from our success. GNU/linux is a truly global phenomenon. Consider all the languages our Fedora Translation team supports. It is encouraging to remember that this challenge is overcome everyday by numerous international and multinational companies.

The English language has a tremendous amount of local dialects, shades and subtleties. Our global audience should be foremost in our minds. We should try to speak and write in clear standard English. An amazing diversity of local dialects of English exist. Our challenge is to write and speak English free of idioms and local color - and still have impact ("pack a punch"). This should be done out of respect for our Fedora users for whom English is a second language.

SOLUTION: Use standard English and be sensitive to differences in language and culture.

WAYS FORWARD

The beauty of FLOSS is that there are many creative people involved in the FLOSS movement. They are faced with the same challenges as we face. Likewise, there are some creative and innovative solutions.

The common challenge is to create useful FLOSS documentation in a timely manner. The documentation must be continually updated as the software and projects evolve. It must be simple to understand yet comprehensive. The documentation must be easily translated into dozens of languages. It must be easily revised and distributed in a variety of formats (HTML, PDF, PostScript, 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, DocBook XML and CVS, along with the installation of some additional software packages.

OTHER RELATED TOPICS FOR DISCUSSION

1. Upstream contribution to other documentation projects (for example, GNOME).

2. Improvements to document conversion tools.

3. Better communication (VoIP, online presence tools [MugShot] )

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

File:JohnBabich SomeIdeas myworkflow.png

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 DocBook for storage in CVS. Note that DocBook conversion may be done manually or automatically.

• Persistent storage, edited DocBook document is checked into the version control system, along with its revision history.

REFERENCES

• "Canonical Source" on FDP Documentation

Fedora Documentation Guide

• Toolset Idea (Fedora-docs-list posting by Paul Frields)

https://www.redhat.com/archives/fedora-docs-list/2006-November/msg00068.html

• How Fedora Release Notes are Produced

Fedora Documentation Beats

• Writing Documents using the MoinMoin 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