Tools used by the Docs Project

In other languages: English (en) español (es) [edit]

This page needs some love
This page should be revised or reconstructed to be more helpful. Problems may include being out of step with current team or project status or process.

Documentation Project Tools

We need a place to discuss our tools. Here are some blank Wiki pages we can fill.

• DocsProject/Tools/ - The page you are staring at is probably all we need, but feel free to (ab)use the DocsProject/Tools/ namespace, eh.
• DocsProject/Tools/Usage - Oh, yeah, wouldn't it be cool to tell people HOW to use our tools? Whee!

- KarstenWade

If you have any questions, please join the list and ask .

Writing

Plain Text and Email

Ideas and first drafts are often written in plain text in the writer's favorite text editor. Concepts, snippets, and first drafts are passed around via email. This practice is a bit old school now, as the wiki has become the preferred draft/scratch space.

Wiki

The wiki is a good tool for collaborative community documentation. Easy to edit, version controlled, instant rendering, and flexible enough to allow for mind mapping .

The Docs team uses the wiki as a place to draft documents before converting them to DocBook XML and putting them under standard source control management. The wiki is an easy way to gather a large amount of raw data, such as the Docs/Beats where the release notes are drafted.

A wiki is a low barrier for entry with a low learning curve. Basic pages are easy to make, and more advanced instructions allow us to make documents that are more easily ported to other formats , such as XML.

Gobby

Gobby is a real time collaborative editing tool. One or more writers can work on a shared document at the same time, with each writer having a unique color to their writing. Writers can write around each other, correcting, adding, and changing the document at the same time. There is an associated chat window for coordination, although many times we continue in IRC instead.

DocBook XML

Writing whole books in DocBook XML is the best way to get the full advantage of this tool. The Docs team uses this format to support publishing and documents over the long term in multiple languages. DocBook has a rich semantic markup that allows a document to be useful for much more than reading.

The Docs team has a set of [#Build_Tools build tools] to manipulate the XML files for translating, styling, and converting to other formats (HTML, PS, PDF, TXT).

Build Tools

Currently FDP uses a customized Makefile, with parts that live with each document that define local variables, and a Makefile-common that lives in the docs-common module in CVS.

Our toolchain is specifically designed to be used as a generic documentation system. This is inline with the project goal of providing a 100% FLOSS documentation toolchain that works within a standard installation of Fedora.

To build a document, you need the document's module from CVS and the docs-common module.

A good module to look at first is the example-tutorial. It's purpose is to be a buildable bare template tutorial. You can obtain it via anonymous CVS:

export CVSROOT=:pserver:anonymous@cvs.fedoraproject.org:/cvs/docs
cvs -z3 login
cvs -z3 co docs-common example-tutorial