Documentation best practice from other organisations

Global Grid Forum

• http://www.ggf.org/index.php
• First document in series sets out documentation requirements (http://www.ggf.org/documents/GFD.1.pdf)
• Authors strongly encouraged to follow IETF Internet Drafts format where possible
• Documents must contain:
  • Document type: GWD-X or GFD-X, where X is one of several types including I(informational), E (experimental), P (Community Practice), or R (Recommendations track).
  • Author name(s), affiliation(s), and contact information
  • Date of the document (original date and revised date).
  • Name of working group or research group (where applicable)
  • Title of document
  • Document URL
  • 1-2 paragraph abstract
  • a summary of security considerations.

Institute of Electrical and Electron Engineers

• http://www.ieee.org/portal/site
• Difficult to find out much about as commercial..
• FIXME -delve deeper on this one

Internet Engineering Task Force

• http://www.ietf.org/
• Detailed document describing document formatting (http://www.ietf.org/ietf/1id-guidelines.html)
  • ASCII text only for standard documents.
  • May have accompanying (but non-normative documents).
  • Documents are the standards.
  • Strong on IP issues.

International Multimedia Telecommunications Consortium

• http://imtc.org/
• Does not produce standards of its own but works with other bodies notably IETF.

International Organisation for Standardization

• http://www.iso.org/iso/en/ISOOnline.frontpage
• Over 14,000 standards and long history.
• Documents are the standards.
• Detailed documentation for docs (http://isotc.iso.org/livelink/livelink/fetch/2000/2122/3146825/4229629/texts_list.htm)

Organization for the Advancement of Structured Information Standards

• http://www.oasis-open.org/home/index.php
• "A specification may be composed of any number of files of different types, though any such multi-part specification must have a single specification name and version number. Irrespective of the number and status of the constituent parts, the specification as a whole must be approved by a single TC ballot. "
• "All documents and other files produced by the TC, including specifications at any level of approval, must use the OASIS file naming scheme, and must include the OASIS copyright notice. All document files must also use the OASIS document templates." (http://docs.oasis-open.org/templates/)
• Templates are provided for working in MS Word, OpenOffice? and XHTML.

Open Geospatial Consortium

• http://www.opengeospatial.org/
• Released as PDF (and white papers as Word docs).
• Appears to be a clear format/template used.
• Can't find documentation documentation on website (may be members only)

Web Services Interoperability Organisation

• http://www.ws-i.org/
• Issue documents are PDF
• Standards ('deliverables') include software.
• Supply MS Word templates for creation of documents.
• Document format is very similar to W3C? format.
• Details may be in members only area.

World Wide Web Consortium

• http://www.w3.org/
• Well defined document rules (http://www.w3.org/2005/07/pubrules)
• Well defined style (http://www.w3.org/Provider/Style/)
• Well defined help on authoring documents (http://www.w3.org/2001/06/manual/)
• Some guides only available to members (http://www.w3.org/Guide/Reports)

-- RogerHyam - 29 Nov 2005