Improving the Docs Project workflow

Old page
This page has been marked as "old", and likely contains content that is irrelevant or incorrect. If you can, please update this page. This page will be deleted if action is not taken.

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.

The Current Setup

Media Wiki - online editing

The Fedora Project is using this approach to produce the release notes and other documents in a collaborative manner. See The Release Notes Process . We have publicly been complimented on the quality of this work.

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

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

Publican - greater versatility

Publican is the open-source tool developed originally by Red Hat and used in-house for its documentation since approximately 2006. This is a great tool for taking DocBook XML and publishing it in HTML, plain Unicode text and PDF.

ADVANTAGES: Open-source tool which handles conversion to three of the most common types of output with built-in support for branding.

DISADVANTAGES: Some learning curve.

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