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.
Herramientas del Proyecto de Documentación
Necesitamos un sitio donde debatir nuestras herramientas. Aquí hay algunas páginas wiki en blanco que podemos rellenar.
- DocsProject/Tools/ - La página que estás viendo es probablamente todo lo que necesitamos, pero siéntete libre de (ab)usar de
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