I think we should focus now on improving the current doc folder. Before starting to write anything I think we have to organize the future of docs to be able to hold any content. Here is my proposal:
- As the doc/index.rst is used as readme it should explain the functionalities of the module (a brief introduction) and link to other files which are relly the docs. Small modules can have only this files.
Other modules may include the following topics:
- configuration.rst: Explanation of the required steps in order to setup the module for usage. For example, on accouting modules we may include the How to create a fiscalyear and the chart of accounts customization.
- usage.rst: Explanation of how to use the module functionalities, how to create a move, how to credit them,etc.
For me one important think of both documents is that they have titles, so they can be shown as a toctree on the index, so the user can see what the modules do an click to show them. Titles should be actions that can be done as this will help the user to discover functionalities via the searcher. For example: Delive goods to customers it will be good title to explain customer shipment functionalities.
What do you think?
Another point that I will like to discuss is if we want to include images on the docs. I think images are very usefull for end user and I will be in favor of including them. The benefit is that the users knows that what he sees in it’s screen is the same screen as the documentation is talking about. I know that images can be outdated and have some diferences due to Tryton modularity but from my point of view this is better than nothing.