Improving the Docs Project workflow

Ideas on Improving the Fedora Docs Workflow

Table of Contents

• Introduction
• Advancing the Project and Community
• Innovative Approaches
• GNOME Tools
• KDE Tools
• Java-based Tools
• Appendix A: The Documentation Workflow Cycle
• Appendix B: Type of Knowledge Contributions to a FOSS Project
• Appendix C: Components of the FOSS Docs Toolchain
• Appendix D: Another View
• References

---

Full Document Print View

---

Introduction

This is a collection of ideas currently being discussed to improve the publication of official Fedora content. These ideas have been raised by various Fedora Documentation Project team members. They are collected here so that the FDP team can review and further refine the workflow process.

Think outside the box

New ideas, suggestions, tools and techniques are welcome.

Please Add corrections

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

The Current Three-Pronged (Three Tools) Approach

MoinMoin Wiki - online editing

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, WYSIWYG editing.

DISADVANTAGES: No automatic tracking of cross-references, no completely automated conversion to DocBook XML, markup lacks semantic meaning (provides visual formatting only).

Plone CMS - cleaner look, content workflow

We can use the Plone CMS (Content Management System) 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, writer <--> editor --> publisher workflow.

DISADVANTAGES: Learning curve in Plone, which includes Zope and Subversion.

DocBook XML - greater flexibility

A contributor can use his or her favorite editor and DocBook XML to publish material in any desired format: web pages, PDFs, Postscript, etc. While some contributors may prefer Emacs, others are free to choose another editor. The advantage of this is the "write once, use often" approach, which is a primary tenet of modular programming and intrinsic to FLOSS. These documents are also the base for the many translations which are produced by our Translation team members.

ADVANTAGES: Flexibility of editors, automatic tracking of cross-references, version tracking, standard "code" base, useful as interim code, transformable into anything, controllable with Makefile in a build system, fits into Fedora Translation and RHEL content infrastructure.

DISADVANTAGES: Learning curve in DocBook and XML (similar to HTML).

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.

Complexity - too many tools and techniques

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

Coordination of Effort - too many projects and priorities

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. We have the tools we need already at hand - we just have to make use of them. New tools are emerging, such as VoIP.

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

Multilingual Teams - too many technical terms and contexts

Technical content that has a clear meaning can be difficult to write. It can be equally difficult to collaborate across language and cultural barriers.

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

The English language has local dialects, shades, and subtleties. Our global audience should be foremost in our minds. We should speak and write in clear, standard English. Our challenge is to write and speak English free of idioms and local color (culture) - and still be meaningful and noteworthy (have impact or pack a punch). This is done out of respect for our Fedora users for whom English is a second language, for the translation teams, and in recognition of the future of Fedora as a multilingual distribution.

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

Next Page - Advancing the Project and Community