End User Documentation

[wifasoi (Luca Cristaldi)]

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?

[pokoli (Sergi Almacellas Abellana)]

@wifasoi

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.

@wifasoi

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…)

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.

@wifasoi

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).

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.

[josesalvador (José Salvador)]

@wifasoi

Wee need an “overview” section in each module.

+1

@wifasoi

So a " Getting started" section should be added to the documentation.

+1

@wifasoi

and not how to do things (something that can change on each release).

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.

[ced (Cédric Krier)]

@wifasoi

It explain quite well the schema of each view the user can encounter

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.

@wifasoi

Wee need an “overview” section in each module.

I do not agree. If you want to have an overview of a module, you just go to the demo.

@wifasoi

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. […]

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.

@wifasoi

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[…]

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.

@pokoli

Howto’s: A list of all the process that are implemented on the module and how to do them.

This is cross module so it can not be documented in the module but in Howto - Tryton Discussion

[pokoli (Sergi Almacellas Abellana)]

@ced

Wee need an “overview” section in each module.

I do not agree. If you want to have an overview of a module, you just go to the demo.

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.

@ced

• We have a setup wizard with such task (maybe we should add more if needed)

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.

@ced

This is cross module so it can not be documented in the module but in Howto - Tryton Discussion

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.

[ced (Cédric Krier)]

@pokoli

so most of the time he will get lost without knowing which functionality it provides.

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.

@pokoli

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 agree. Wizard should not be used to create records. This is the role of Blank state improvements

@pokoli

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.

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.

@pokoli

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.

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.

[pokoli (Sergi Almacellas Abellana)]

@ced

That the point of the general description.

Ok so we agree that the module needs a general description. Good!

@ced

I think it should not contain screenshot as long as we can not maintain them

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.

@ced

I think also there is a maintenance problem with the link pointing to the demo.

I agree about the demo link, just added to see if this is something that end users will expect or not.

@ced

But as I said, I do not think howto’s should describe the requirements steps because it is the job of the error message.

Well, the idea is to let the user know what is a fiscalyear and what is used for.

@ced

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.

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:

• Odoo
• ERPNext
• SAP
• Dynamics 365

@ced

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.

Could you write one as example to see your way and find some common patterns to write them?

[ced (Cédric Krier)]

@pokoli

I’ve done a little bit of reasearch to see how other ERP systems document a fiscalyear. Here are my results:

• Odoo
• ERPNext
• SAP
• Dynamics 365

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.

[coogor]

@ced

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.

[uha4 (Ulrich)]

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.

[nicoe (Nicolas Évrard)]

@coogor

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.

What can be done to enable you to write this end-user documentation?

For example this question would make an good how-to:

Is there in Tryton handling of shelves?

That is to be able to create the shelves, indicate the floor on which it is, etc.

How can we get you started with writing an howto regarding this question?

[coogor]

@nicoe

@coogor

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.

What can be done to enable you to write this end-user documentation?

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.

[timitos (Korbinian Preisler)]

@coogor

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:

Howto

You wrote a wiki would be a start and this section can be used as a wiki.

[nicoe (Nicolas Évrard)]

@coogor

What can be done to enable YOU to write some documentation?

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?

@coogor

(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.)

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).

[coogor]

@nicoe

@coogor

What can be done to enable YOU to write some documentation?

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?

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.

[pokoli (Sergi Almacellas Abellana)]

@coogor

And about a missing platform for this

Could you (and other community members) describe the qualities that should have the platform that you say that is missing?

The objective of this discussion is to dream about the perfect Tryton platform and work hard to achieve it!

[nicoe (Nicolas Évrard)]

@coogor

I did not ask what the project can do for me - please don’t turn the words in my mouth, or get personal.

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?

@coogor

d.t.o is obviously not accepted as such tool

By who?

[albert (Albert Cervera i Areny)]

Just to throw another idea:

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

Just my 2 cents

[pokoli (Sergi Almacellas Abellana)]

@albert

We could use Bootstrap Tour or similar (adapted to Tryton).

IIUC correctly this is only avaialbe for sao. Is there any similar option for GTK?
We should develop the same functionality for both clients.

[Unai (Unai Mandaluniz)]

I agree with Ulrich. I think he summarizes well my own ideas.

As a end user, I miss A LOT some documentation explaining the basic processes in Tryton. I am used to this kind of documents in other ERP and other kind of softwares and they are completelly helpfull. Also think about when you have to train someone new…

I think of it as a part of the quality system (let’s say ISO9001 for example) where it is highly recommended to write down the processes together with their fluxes.

The only point I would disagree with Ulrich (slightly) is that I also find that field listing is helpfull. I don’t find necessary long explanations but a resume would also help so you can quickly remind the functions. I don’t find it as necessary as writen info but would also help.