I created few days ago the howto categories like planned and we got a nth never ending topic about documentation. But I could not find any actual plan nor organization.
So now we have two “howto” topics that for me are in the wrong place. They are description of two simple process that should be have been written each one in the proper documentation of their module.
I think it is crucial to have proper organization otherwise it will be a mess that will be unmaintainable and like for all previous initiatives it will just die.
So here is my proposal to organize the documentation:
- define a field must be only done as help text on the field.
- describe a model (like what is fiscal year) must be done only in the
docfolder of the module defining it for the first time. This include also its eventual workflow and also what other documents it creates.
- explain a wizard (like the refund invoice) must be done only in the
docfolder of the module.
- howto’s are for complex tasks that involve many concepts and are cross-modules. E.g. howto import initial stock (create products, set proper cost, create an internal shipment from supplier, etc.) Or howto organize location (list of cases, pros/cons of each one, performance concern etc.)
The other points to help the user are:
- error message which should explain the problem and provide a solution.
- the support category
- the future blank state
- the setup wizards
If we want to succeed in documenting Tryton, we must stick to the schema and have everyone to contribute. Indeed each time a support is answered, we must:
- try to answer by pointing the proper documentation (not write one as comment)
- try to improve documentation to avoid such question in the future (but stick with the schema)
Another point to improve the actual https://docs.tryton.org/, we should add for each model the path to to it in the menu and set it as an URL pointing to the model on the demo server like this:
Financial > Configuration > Fiscal Years > Fiscal Years
Remarks the usage of unbreakable spaces and not using database depend value like view_ids.