This wiki is obsolete, see the NorduGrid web pages for up to date information.

Documentation writing

From NorduGrid
Jump to navigationJump to search

ARC documentation guidelines

Where to find ARC documents

Document types

ARC has three types of internal documents:

  • MANUAL - usage or installation instructions, tutorials and similar documents, oriented towards customers
  • TECH - technical documentation of software components, oriented towards developers
  • MEMO - short notes and memos, typically about 3rd party tools


At the moment, documents are assigned identifiers NORDUGRID-type-number. List of known documents is kept in the LaTeX .bib file in the code repository.

Document repository

All ARC documents MUST be in the dedicated repository:

The repository is organised as follows:

  • manuals - contains documents of the type MANUAL
  • installation - dedicated to manuals and notes on installation
  • tutorials - dedicated to tutorial manuals
  • tech_doc - contains documents of the type TECH
  • miscellaneous - contains documents of the type MEMO
  • templates - contains document templates (HTML and LaTeX)
  • release notes - contains Release Notes
  • examples - configuration examples
  • EMI - EMI project-specific documents and templates
  • debian - auxilliary folder

Document preparation

  1. ARC documents are prepared and maintained like the code, in a version management system (currently SVN).
  2. Document source must be a portable ASCII file (e.g. LaTeX, HTML, XML or plain text)
  3. Published documents must be in either PDF, HTML or plain text formats
  4. Each document must receive a unique identifier from the ARC documentation coordinators

Allowed source formats

  • LaTeX: preferred format
  • HTML: generally accepted for some manuals, like e.g. installation or configuration instructions
    • optionally, XML+XSL set is acceptable, if it is complete with a Makefile that creates HTML
  • plain text: only for Release Notes

LaTeX guidelines

  • Use the templates and bibliography files from
  • Use Makefile template - documents are built just like code
  • Avoid using styles and packages which may not be available in default teTeX/TexLive distributions - keep it simple
  • Avoid using WYSIWYG tools which pollute source with tool-specific styles - don't use LyX
  • Avoid including pieces of code by reference - use copy and paste

HTML guidelines