The documentation, right now, is a bit dry:
It explains only what fields are, but not how the workflow of the module works.
For example the account module:
It explain quite well the schema of each view the user can encounter, but it lacks how the accounting workflow is implemented in tryton. Wee need an “overview” section in each module. It should just describe how each view/schema interact with each other, without going to much in the details.
Something like this can be very helpfull:
The main task of the accounting module is to define the company Chart of account (via a template or manually created by the user) and keep track of accounting move divided by Fiscal year. […]
This give a short overview on how the module works, and give some context on all module keyword (like fiscal year, chart of account, ecc…)
Another important aspect is what are the step required by the user to make a bare bone configuration. So a " Getting started" section should be added to the documentation. For example in the account module, you can have something like this:
Before you can create an accounting move, you should define a fiscal year. In the fiscal year you can define periods and configure the auto numbering rule for each accounting move[…]
This kind of documentation is direct, short and relatively easy to maintain because it describe how the workflow is implemented (rarely change), and not how to do things (something that can change on each release).
Another point is that we can gradually document the modules: we don’t need to “carpet documenting” all the things, but we can start slowly as a code review rule for new module (for example).
And what about creating a small widget/module for sphinx that create a small viewport(with inside a Sao page) that point to a specific module/view? So the user can play around with the module without changing context. What do you think?
I think this will be something that we are not currently able to provide as we do not have nothing to show. So we should first improve the documentation and latter discuss this kinds of integrations.
So IIUC you propose to structure the documentation in the following parts:
Glosary: Introduction of concepts used (which is what we already have)
Getting started: What the user needs to setup in order to make the module work.
Howto’s: A list of all the process that are implemented on the module and how to do them.
I like this idea, specially as we can add links from the howto’s (which should be the main part) to the glosary or the getting started topics that are relevant to the current topic.
I completly agree here but probably the best will be to start documenting one process and see if the proposed structure works well. Probably we can start by documenting: How to create an accounting move, which will require to explain the fiscalyear, periods, accounts, and how to create them.
For me, it was a mistake to do that because it is almost always forgotten when something change.
You can see in the new module, we do not write such thing any more but just a general definition of the features implemented by the module.
I do not agree. If you want to have an overview of a module, you just go to the demo.
I do not see the point because:
We have a setup wizard with such task (maybe we should add more if needed)
We have good error message that guide the user to solve it problem.
I do not see neither the point of such documentation (except added more load to the maintenance).
Such requirements depend on many variables that it will never match someone workflow. But also it is the job of the error management and the blank state pages to guide de user.
So for me, if you think we need such “documentation”, it means we have to improve the user experience instead.
I do not think a new user can discover what a module does by activating it on a demo database. For example the sale_price_list module adds the price_lists to the sales but the user will not know how to setup a price list without any proper documentation, so most of the time he will get lost without knowing which functionality it provides.
I think we should add at least one more wizard:
Create a fiscalyear
But probably we should et the user configure some default values for the system. For example, when activating the price list module we should ask them to create some price list (like we do for users). Same for invoice payment methods, payment methods, statement journals, and so on.
I do not think most of the user functionalities are cross module. For example the sale module can describe the general workflow for sales and then each specific module can include a howto for it’s specific case (i.e: How to set specific prices for a customer). Otherwise it will be impossible to document all the possiblities.
I’ve just created a how to create a fiscalyear topic so we can discuss with an example case. Feel free to review it an give some feedback about how it can be improved.
Altougth this tutorial is for 5.4 version, this has changed on trunk version, so I will like to know how we plan to manage such changes by using a wiki. One of the reasons that I prefer to have the documentation included as part of docs.tryton.org is that it can be versioned. This is something important since we have LTS versions that will be supported for 5 years, so we should also give a proper documentation while the version is suported.
That the point of the general description. Maybe we do not talk about the same thing for “overview”. For me “overview” means to describe in short term everything that is visible. That’s why I said it is the demo role.
I do not agree. Wizard should not be used to create records. This is the role of Blank state improvements
I think also there is a maintenance problem with the link pointing to the demo.
The fiscal year is not only required to post a move. It is even for just create one.
But as I said, I do not think howto’s should describe the requirements steps because it is the job of the error message.
This is because we must not describe the UI in an howto but the general steps.
For me, the “create a fiscal year” is not a good howto because it is just about filling a form. This would be better covered by a short tutorial video.
To be very clear. The “how-to” should be the thing we wrote after solving a support topic to summarize the solution to the complex problem. For example, it can be: how to import the initial stock quantity, how to close a partially shipped sale or what are the steps to prepare the closing of a fiscal year. So it is complex workflow that involve multiple documents with large implication.
Ok so we agree that the module needs a general description. Good!
Why we can not maitain it? I think it’s better to shown an image to the user (so he knows it’s on the right place) than nothing. Whenever we use images or videos the what the user sees on the how to may always be diferent due to the modular design of tryton. So I’m in favor of keeping it simple and add some screenshots, which can be easly updated.
I agree about the demo link, just added to see if this is something that end users will expect or not.
Well, the idea is to let the user know what is a fiscalyear and what is used for.
From the user point of view, everything that he should enter is a form
I’ve done a little bit of reasearch to see how other ERP systems document a fiscalyear. Here are my results:
Not too far from what we already have: Account Module — Tryton module for accounting (except the field listing which should be replaced by sentences).
Any way, I think the SAP one should be our model.
‘Not far’ is relative: In galactic dimensions, the distance to the moon is negligible. If you have to drive it, you will see it different.
Tryton ‘documentation’ is a technical listing of fields. This is not documentation at all and useless for the end-user. There is nothing that provides the big picture, that explains the ideas and concepts behind the modules. This is basically what @wifasoi asks for, and he is right.
I agree, that a functional documentation would help a lot and i think even the best Error Messages can’t replace it. It is still like a try and error approach when you try to fill a form, and get than an error hinting you to what to do first. Than you try this and get the next error what to do first. For me this is frustrating, it would be much easier first to read how everything works together, and then start doing it in the right order and knowing what is next and what is influenced by what I’m doing now.
Perhaps this could be done in a tutorial video, but in a video you can’t search, you cant skip a chapter or some (just for me) irrelevant details that easily. The next point is, that reading I’m usually faster than somebody speaking, and a written word you don’t understand is easier to paste to translation or google it.
I know humans are different, so I just wanted to cast my vote for a written documentation that focuses on the functional connections and ideas more than listing the fields.
What can be done to enable YOU to write some documentation?
(I received - by PM - the question of a user: I have a Tryton-server on machine A and a client on machine B - how can they talk to each other? - I feel there is enough stuff to write about.)
To paraphrase Kennedy: don’t ask what the project can do for you but what you can do for the project. This is free software: you can’t expect people to do something for you ; if they do, fine ; if they don’t maybe you can help and more often then not any help is appreciated.
So I’ll ask again, how can the project helps you write an howto?
It’s not exactly an howto in this case, it’s more a support request as numerous similar questions on this forum shows it (the heterogeneity of the network environments makes writing an howto on this subject extremely difficult - if people want a simple installation procedure the docker image is probably the way to go).
I did not ask what the project can do for me - please don’t turn the words in my mouth, or get personal.
The discussion is about a missing end user documentation. And about a missing platform for this. d.t.o is obviously not accepted as such tool, not to mention that the ‘documentation’ link on tryton.org is pointing to the technical documentation at Tryton Documentation — Tryton Documentation.
You asked me what can be done to enable me to write end-user documentation.
I’ll reply then: a lot of time (but the Tryton project can’t do anything about that).
And so how can the project helps you write an howto?
We could use Bootstrap Tour or similar (adapted to Tryton). It’d have several advantages:
No audio required (although maybe it could also be the basis of automated videos)
It’s better than video because it allows the user advance at her own pace
No need to update screenshots on each release
It could be extended by modules (something similar to view’s position to add tour elements before or after other elements)
The user could get the information when she needs it (maybe the global search could show available tours, or a “?” icon could be added)
It could make maintenance easier than other options:
Tests could identify that a field no longer exists and so an element linked to the field should be removed
It could show existing tooltips in order of appearance (yes, users can discover tooltips one by one, but tour would make them visible and would not force the user to hover over 10 fields only to find that 5 of them don’t have tooltips)
As it is guided, probably less wording is necessary compared to standard documentation
At the same time it allows adding some workflow information on the first steps of the tour. The kind of information that does not fit in tooltips or error messages.
It could be translatable using Tryton’s infrastructure
