This wiki is obsolete, see the NorduGrid web pages for up to date information.
Documentation writing
From NorduGrid
Jump to navigationJump to searchARC 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:
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
- ARC documents are prepared and maintained like the code, in a version management system (currently SVN).
- Document source must be a portable ASCII file (e.g. LaTeX, HTML, XML or plain text)
- Published documents must be in either PDF, HTML or plain text formats
- 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
