[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ A ] [ next ]
Articles are included in the Debian Documentation Project mainly as a way to keep for short documents related to Debian and written by developers (or other people that want to contribute it to the Debian Documentation Project). Articles are not in-depth documents (manuals are). However, it is not uncommon for Debian developers to write articles for magazine (online or paper-based) or to analyze a given aspect in Debian (usually for conferences).
Articles can, unlike manuals, get out of date and not be updated. That is not an issue since the knowledge they hold might be useful even if in such state. The intention include them in the DDP and make them available through CVS is so that it is possible to publish them on the WWW (like other DDP documentation) and to provide a repository of knowledge for later use. After all, articles, even if outdated, can be used to write new articles or might reflect an important epoch of the Debian project.
Articles are located in the DDP CVS under the articles/ directory.
Each article is in its own sub-directory which must contain a README
file with the following information in its header:
title: Article title
author: Author's name
published: Where has it been published (if anywhere)
date: publishing date
update: date it has been last updated (usually it's the same as date:)
The documentation format in articles is, unlike that of
manuals.sgml, not standardized. Debiandoc-sgml is still
preferred, but, due to its limitation (described previously) sometimes authors
might prefer other formats (such as Docbook-xml or LaTeX). These can be used
for articles. However note that if the author uses a format which cannot be
easily compiled on the documentation server for publishing, the DDP might not
dedicate effort to have the documents published. Formats that can be readily
compiled from source format into the publishing formats of manuals (HTML, text,
PDF and PS) have more chances of being integrated in the publishing tool chain.
For this reason, articles, when possible, should be translated from their documentation format to the preferred format of the DDP (currently debiandoc-sgml). Some articles might be found, however in linuxdoc-sgml. These articles need to be translated to debiandoc-sgml before publishing is made. This is because there are no fundamental differences between both formats to justify using linuxdoc-sgml.
[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ A ] [ next ]
Debian Documentation Policy (DRAFT)
[email protected]