I do not agree. People are lazy. You can see that on this forum by how much similar question we got or how people does not even make research before asking (I answer often with a link to the documentation).
What should they research for? There is no wiki anymore since ages. ‘No documentation’ is a massive weakness in this project…
Every page in this tool (discourse) can become a wiki page. But in my experience wiki is the wrong solution for writing documentation.
Altought I a wiki can be an starting point I will prefer if the documentation (howto’s, videos) resides on readthedocs or similar, which can be versioned.
2 Likes
I think we all agree on this point, the idea of this discussion is to improve it. It will be great if you can help us to have some material to guide end users on how to use Tryton. You knowledge in this area will be very usefull.
1 Like
I feel we need an alignment where and how to set-up documentation and how-to. A wiki may not be ideal, but a good start
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).
2 Likes
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.
1 Like
+1
+1
I think exists a lot of common user cases that rarely changes in each release netiher workflow too and deserves a howto section as said before.
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.
This is cross module so it can not be documented in the module but in Howto - Tryton Discussion
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 it should not contain screenshot as long as we can not maintain them (see Scripting Tryton Tutorial Video).
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:
Could you write one as example to see your way and find some common patterns to write them?
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 this end-user documentation?
For example this question would make an good how-to:
How can we get you started with writing an howto regarding this question?
3 Likes
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.)
And as written in post End User Documentation - #9 by coogor , we need a platform for this.
But the platform is already there. It is this section:
You wrote a wiki would be a start and this section can be used as a wiki.