Proposal to improve the documentation structure

Feature Ideas
1

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 ModelStorage. write method takes.

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.

Project: readthedocs

Tryton

Introduction and description of what Tryton is, how it is structured and which parts of the documentation may be useful to the reader…

User Documentation

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?

Developer Documentation

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.

Project: trytond

Tryton Server

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…

Installation

Information on installing Tryton…

Configuration

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, trytond-cron, etc… services and trytond-admin command…

Developer Documentation

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)

Desktop Client

Introduction to the desktop client…

User Documentation

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…

Installation

Information on how to install the client…
How to install plugins…

Configuration

Where the configuration file is located, what options are available…

Developer Documentation

Documentation on things like plugin creation, etc…

Project: Module (for each module)

This is described in the proposal for Documentation on the proper place.

3 Likes
2

First, thank you Dave, it’s a great job. I love it.

Now my two cents:

I bet for the three categories you propose. The only change I would do is moving the documentation related to people who are in the administration groups in Tryton to users category. Maybe noting that kind of documentation to the admin user.

The last change I would IMHO is related to the Project: Client:

As far as I understand the aim for both clients is to give the same behavior, look and feel to the Tryton user, so I wouldn’t build one documentation for each one else only one noting the differences that they have when be required.

2 Likes
3

I think we all agree that there are three kinds of audiencies on the main documenation page:

  • Users
  • System administrators
  • Developers

So I think the main usage of this page is to allow each user to find it’s related documentations (and forget about modules and projects, this is not relevant for our readers).

So I think the best is to provide a single file for each of this audiencies. Each audicence should be able to reach it’s section from the index page.

The user section may be something like:

  • Learn how to use the tryton clients.
  • Learn which features are avaialbe on Tryton (list of modules with each feature)
  • How to use the features (All the modules documentation)

Probably adding an introduction to explain what the user can find on this sections is a good idea.

The system adminstrator and developer documentation is mostly explained on the server documentation, so I think we should include an introduction an relevant links in this sections.

1 Like
4

Hello, my humble greetings to everyone here.

I’ve been going through the post here. I must confess that you (the organization) are really super awesome.

I actually came across this organization as a result of searching for the GSoD 2020 organization to work with, and have developed an immense passion to contribute to this amazing family.

I’ve been able to clone all the files of the Documentation, though a tricky one. Initially, I found it difficult to clone the entire documentation due to the structure but finally got an idea that helped me clone it fully to my local machine and arranged it according to the current structure.

Currently, I am studying it to be able to figure out where each category should fall in and also to add some other features like code copy button (though I already implemented it on the one I cloned)

I’ll be using GitHub for testing (don’t know if this will be a good idea), reason, to avoid complicating issues with the already existing documentation in which after a thorough check and corrections by these great organization members, it will then be pushed to the main repo. But I’ll be okay with which tool that works best for the organization.

Meanwhile, I am 100+% open for your guidance in achieving this.

I am super excited to discover this great organization.