The Documentation on the proper place thread proposes a sensible method of organizing the documentation for fields, models, wizards, and cross module tasks. It also mentions the other places where help and guidance is provided. If we can follow this then I think we will end up with good maintainable documentation for the Tryton modules.
I would like to complement that with a proposal for some changes to the top level structure of the main Tryton documentation to help make best use of that documentation, and possibly fill in some gaps that may appear.
There are a wide range of different people who work with Tryton. If they have arrived at the documentation, then they are looking for some information. I think they can be broadly split up into one of three categories:
- Users: these are people who are using either the web or desktop client and are looking for information on how to use the client, or perform tasks like creating a new party, or crediting and refunding a posted invoice.
- System Administrators: these people setup Tryton for the Users. So are looking for information on installing, configuring and running Tryton. They will also include the people who are in the various Administration groups in Tryton. They may be trying to find out what they need to do to get scheduled tasks to run, or what steps they need to take to setup the accounting module once it is activated.
Developers: the developers are people who are developing Tryton itself, or are creating modules for use with Tryton. They may be looking for information on what the structure of a module is, how to setup module tests, or what arguments the
Obviously there is some overlap between these categories, as people who are setting up Tryton for themselves will be both System Administrator and User of their Tryton system, and people creating reports may be the System Administrator, but will probably need to also refer to some of the Developer documentation.
Based on that I would like to propose restructuring the documentation as follows. Note: As Tryton is made up from many projects (client, server, modules) I have added a section below for each project/group of projects.
Thoughts, comments, better ideas, and improvements are welcome.
Introduction and description of what Tryton is, how it is structured and which parts of the documentation may be useful to the reader…
Overview of Tryton from a user perspective, what clients are available, etc…
Link to the User Documentation section of each client’s documentation.
Link to the Howto/User section on discuss.tryton.org
Link to the Module documentation, maybe the specific User Documentation parts?
System Administration Documentation
Overview of Tryton for a system administrator…
Link to the server System Administration documentation.
Link to the System Administration documentation for each client.
Link to the Howto/System Administrator section on discuss.tryton.org
Link to Module documentation, maybe specific System Administration parts?
Overview of Tryton from a developer’s point of view…
Link to the server Developer documentation.
Link to the Developer documentation for each client.
Link to the Howto/Developer section on discuss.tryton.org
Link to Module documentation, maybe specific Developer parts?
Reference / Links
A section with links to the top level of the each project’s documentation. Similar to the current contents of readthedocs, but maybe slightly more condensed.
Introduction to the Tryton server, how it fits in with the other parts of Tryton, etc…
System Administrator Documentation
Overview of the Tryton server from a system administrator perspective…
Information on installing Tryton…
Information on the
trytond config file and log config file, and the configuration options for the server, possible links to the module config options in the module documentation?
Services and Tools
Documentation on the
trytond-cron, etc… services and
The documentation from the current trytond documentation that is aim at developers, such as API docs, testing, module creation, etc…
Project: Client (one for web and one for desktop)
Introduction to the desktop client…
The basics of how to use the client, sections for toolbar, menu, etc…
Information about concepts like model, view, wizard, relate, etc…
System Administrator Documentation
Overview of the client for system administrators…
Information on how to install the client…
How to install plugins…
Where the configuration file is located, what options are available…
Documentation on things like plugin creation, etc…
Project: Module (for each module)
This is described in the proposal for Documentation on the proper place.