[ previous ] [ Contents ] [ 1 ] [ 2 ] [ 3 ] [ 4 ] [ 5 ] [ 6 ] [ 7 ] [ A ] [ next ]

Debian Documentation Policy (DEPRECATED and OLD DRAFT)
Chapter 4 - Articles

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.

4.1 Content organization

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 (DEPRECATED and OLD DRAFT)

CVS, Sun, 06 Feb 2011 16:44:38 +0000

Debian Documentation Project debian-doc@lists.debian.org
Authors, Section A.1