IntroductionThe documentation of a module should address the following issues: - Module Documentation
- should extend the general documentation and therefore it:
- should not repeat the contents of the general documentation
- should not replace the general documentation
- should be very similar in structure for easier maintenance and reading.
- should be as short, complete and explicit as possible
- should avoid long examples
- ince this indicates that the reference part of the description is:
- not explicit enough
- not complete
- too short
- should have no screen shots
- the text should be descriptive enough to be understood without screen shots
- should be easily translatable in different languages
- the best plan put forth is to translate paragraph wise via get-text
Template for Module DocumentationThe following template describes the general structure of a documentation page for an individual module. Module Name- File or package name
- Link or explanation of how to obtain the module.
- Try to not duplicate the module's tryton.py file.
- This file and the general structure of a module are described in the general documentation.
Short Description- One paragraph about the general function of the module
Menu Entries- Collect and briefly describe all menu entries the module generates.
Foreach Menu Entry: Menu Entry Name- Some introduction sentences about the Form.
- Don't repeat the Short description!
- Leave it empty, if there is nothing more to say
View- Which Type of view opens?
- Describe the view without going into too much detail.
Fields- Which fields are in the view?
- Describe Function of each Field
- Don't describe the function of field types (char, one2many, many2many)
- They are described in the general documentation
Actions- Are there actions in this view?
- Describe all actions of the view
- Don't describe all standard actions of all views.
- They are described in the general documentation
Wizards- Are there wizards in this view?
- Describe all wizards of the view
Workflow- Are there workflows in this view?
- Describe all workflows of the view
Reports- Are there reports in this view?
- Path and file name of the report template
- Describe all report variables of the view
Install/Upgrade/Uninstall- Document any special needs this module has to:
- be installed
- be upgraded
- be uninstalled
- Don't collect general steps for all modules
- They are described in the general documentation
ReferencesExternal Documentation- Links to howtos, tutorials, wiki pages, forum entries, bugs or IRC logs.
|
Sign in to add a comment
