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.