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.