Documentation writing

From NorduGrid
(Redirected from Instructions for authors)
Jump to: navigation, 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

Numbering

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 http://svn.nordugrid.org/repos/nordugrid/doc/trunk/templates/tex/
  • 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