Differences between revisions 10 and 11
Revision 10 as of 2007-11-28 13:33:53
Size: 1895
Comment:
Revision 11 as of 2008-01-03 13:48:05
Size: 1899
Editor: localhost
Comment: converted to 1.6 markup
Deletions are marked like this. Additions are marked like this.
Line 23: Line 23:
You can use the following template as a starting point for your documentation: attachment:DocumentationTemplate You can use the following template as a starting point for your documentation: [[attachment:DocumentationTemplate]]

Guidelines for creating documentation

This document provides general guidelines for authors of ERP5 related documentation. Please read it carefully to help us make the documentation consistent and usable.

  • The documentation should be in English (UK)
  • The documentation should be created with OOo 2 Impress
    • the slide should show the idea visually
    • the notes page should explain it
  • On the notes page
    • bold type should be used to highlight new ideas which are shown in the visual part
    • italic type should be used to highlight code or user interaction (button names etc.)
  • Notes pages which are too long to be printed on the page have to be split into two slides
  • Please use a spellchecker
  • The first person plural (we) should not be used
    • Bad: "After we have installed the module"
    • Good: "Once the module is installed" / "After the module has been installed" / "After you have installed the module"
    • Bad: "We can configure the module by [...]"
    • Good: "One can configure the module by [...]" / "The module can be configured by [...]" / "You can configure the module by [...]"
  • Use capitalised words when referring to ERP5 specific entities like modules. For example, use ERP5 Base instead of ERP5 base.
  • If you use transparent objects, only use 100% transparency not less. Otherwise it will be problematic to display the transparancy correctly for some pdf viewers if a pdf file is generated. kpdf will ignore the transparency, xpdf will display it correctly for example.
  • Set the properties of the document (File->Properties)

  • Always use styles (Format->Styles and Formatting) to make sure that changes can be made easily (just change the font size in one place etc)

You can use the following template as a starting point for your documentation: DocumentationTemplate

Please comment and add your suggestions.

GuidelinesForDocumentation (last edited 2008-01-03 13:48:05 by localhost)