m (Fixed template)
Revision as of 02:09, 22 February 2009
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!
If you have any questions, please join the list and ask .
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.
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 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.
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).
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
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:email@example.com:/cvs/docs cvs -z3 login cvs -z3 co docs-common example-tutorial