Documentation writing

ARC documentation guidelines

Where to find ARC documents

• Web: http://www.nordugrid.org/manuals.html
• Distribution: nordugrid-arc-doc package
• In your computer: /usr/share/doc/nordugrid-arc-doc (Linux)
• Sources: http://svn.nordugrid.org/repos/nordugrid/doc/trunk/
• Building from source: Documentation/Build

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:

• http://svn.nordugrid.org/repos/nordugrid/doc/trunk/

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

• Use the template from http://svn.nordugrid.org/repos/nordugrid/doc/trunk/templates/html/
• Wiki pages are not considered official documentation - in case you started writing a document in Wiki, convert it to a regular HTML as soon as it is ready to be distributed