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 doc folder 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 doc folder 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.
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.
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.
I think this has to be managed case by case like it is already the case (see the timesheet module).
Not necessary. Again this will be chosen case by case.
I’m strongly against because it is a nightmare to manage (except if there is some automating tools). We have multiple clients which render differently (web vs desktop, themes, screen size etc.).
I think overall this is a good structure for the documentation.
One additional thing that I think would be good, where possible, is to try and keep the documentation that is intended for developers, system administrators, and users separate. Perhaps in separate sections or files. I know there will be overlap between these audiences, but as an example I wouldn’t be expecting most people to ever need to run the xlstproc command to localize the minimal account charts, but this just happens to be the first thing mentioned in the account module documentation.
Could you clarify what you mean by this?
Personally I think it will be easier, at least initially, to not have images, especially if we can provide a link through to the demo server. If a good way of maintaining images can be found then they could be added later. One question I have though is, how will links work for modules that have not been activated on the demo server?
As a starting point, do you think it would be a good idea to create an issue to update the account module documentation. I could then have a go at updating it to match the proposal, and incorporate the Financial Year howto?
So you can write :tryton:'account.fiscalyear' will be substituted with https://demo5.4.tryton.org/model/account.fiscalyear when compiling.
This has the advantage to have older documentation that point to the correct tryton demo for the older series.
Another advantage is that the link can be changed globally.
How about adding many more tutorials in the “How To” section? There are hardly any, currently. I’d start out with the most common things a new user would want to do (whether that new user is a user, admin, or developer).
Whenever I Google stuff, I’m always finding helpful tutorials on Digital Ocean, for example. Digital Ocean really wants people to use their cloud platform, so they’re always making it easy for developers to figure out how to deploy stuff there.
I’m sure you guys could create a new tutorial on any topic in about 20 minutes. If only you had at least 10-20 basic tutorials to get people started, perhaps you’d need to spend less time answering questions. For example, I can see the cool “demo” site, but how can I create it myself? I think there should be a tutorial for that, broken into bite-sized chunks.
Personally, that’s what I’m looking for right now (tutorials). First I did the dev stuff to get the Postgres database and server running. Now the hardest part is user/admin stuff like figuring out how to install (activate?) modules, create users and companies, and everything that goes with it (currencies, countries, payment terms, etc).
I just want to get to the point where IJACK employees can login through a web browser (done), create an invoice, and populate it with customer info (from dropdowns) and product info (items sold). Then I think I’ll be off to the races. Eventually IJACK Technologies Inc would love to replace QuickBooks Pro with Tryton, but probably not until at least January 2021 for practical reasons.
Thanks a lot,
Sean McCarthy
IJACK Technologies Inc
I have just been reviewing the account_es_sii module, and noticed that the configuration options for the module are included in the module documentation instead of the trytond/doc/topics/configuration.rst file.
For me this is not a problem, in fact it seems more modular to document them in the module that uses them, but I was wondering what you think is the right place for them?
I understand that some of the configuration option may be used by several modules, which may make documenting them in a module problematic.
It must be documented in the module that defines them. All module configuration must use the module name as section so it should be clear in which module each option should be documented.
I’ve been thinking about this, and from the reviews of documentation that I have looked at so far I think this would be quite a good idea. I know we need to look at each module individually, but I think doing something like this would give a nice structure to the documentation, and would help to keep some consistency across the module documentation. Perhaps files for things like?:
configuration.rst: the configuration options that are available in the module.
setup.rst: description of any setup / scripts that can or should be run to setup the module ready for use.
usage.rst: documentation on how to use the module, possibly containing information on wizards and relates if applicable?
models.rst - descriptions of the main models that are introduced by the module.
user_application.rst - any routes the module makes available for user applications.
etc…
This would then leave the doc/index.rst file free to be a description/overview of the module and which would act as a good long_description for the package and PyPI.
On a separate / related point, the Documentation links on PyPI point to the general Tryton documentation. With some of the module’s documentation now being in separate files, which are not included in the long_description do you think it would be better to link to each module’s individual documentation instead?
I think it makes totally sense to make the module point to each other documentation.
Also it will be good to have a links folder at the end of the file for some people that read the code from sources (not on PyPI), like it’s on on flask package.
Sounds good but IMHO I think we may begin to keep it as simple as possible moreover at the initial stage, so I would merge, at the moment, some topics in a more simple structure as @pokoli proposed.
Having a general, models, configuration and usage sections is IMO a simple and well understood structure that has a good separation of concepts.
What do you think we should do for models that do not have a menu entry? I am currently thinking that if a model does not have a menu entry, then we probably don’t need to document it?
For example:
Current documentation includes Address Subdivision Type, but there is no menu entry for it.
I think we must not make strict rules about documentation.
We do put a menu entry for a model because it is useful and we do not if it is not useful.
I think there are valid case where we need to document a model that does not have a menu entry. In such case we could just not put a link or put a link but without the menu path or put the link of the parent model that contain it.
For the case of address subdivision type, I think it is important to document it because must understand how to use it.
I think that accessing the documentation from the Tryton client would be important, it becomes more visible and although it involves several challenges such as translation, categorization, among others, it makes it more important and useful.
This would be possible by adding an icon in the act_windows
Initially it can only show the information of the doc/ directory of the module to which the act_window is linked but if the structure is adjusted (as it is being proposed in this thread) it could be filtered by model, view or wizard.
I think we are far from this point as we miss many documentation. The client is capable of showing a help string for each field but there ara many modules that do not have this documentantion set.
For me we should focus on documenting first and then we can think on a solution on how to integrate it with the clients.
