End User Documentation

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.

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.

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!

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?

By who?

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

1 Like

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

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.

1 Like

Hey guys,

I’m a potential new Tryton user searching for documentation and I’m disappointed so far. I’ve watched @ced’s videos and he seems like a great guy, but I completely disagree that Tryton shouldn’t have documentation. I’m shocked he would say that, actually. Now I have to ask questions, because I can’t find the info myself. I’m a very experienced Python, Docker, and PostgreSQL user too, so Tryton seems perfect for my company–except how the heck do I get started?

For me, all it would take to get me started is one docker-compose.yml file, to setup all the services. Does anyone have one handy? That’s much better for CI/CD deployment than doing several separate docker run commands, IMHO.

Thanks a lot!

Sean McCarthy
Chief Data Scientist
IJACK Technologies Inc

You can take a look to the Tryton demo compose file to get inspired.

Hope it helps you.

1 Like

2 posts were split to a new topic: How to setup SSL for Tryton

This Coopengo training is by FAR the best source of documentation I’ve found for new users. It’s absolutely terrific and easy to follow step-by-step. If you haven’t seen it, take a quick look.

Here are some observations of mine, from a brand new user’s perspective (I just started using Tryton yesterday). I think with just a little bit more guidance for brand new users, Tryton adoption could really take off, especially among small- to medium-sized businesses not wanting to pay a fortune for big ERPs and expensive consultants.

Firstly, just getting a development environment setup is tricky with Tryton. Sometimes “pip install tryton” actually fails due to pycairo, which is a bad first experience!

Second, it’s not immediately clear to new users (even very experienced developers) that they must deploy the server first (somewhere… could be localhost:8000 or AWS EC2 port 8000). Sure, maybe it’s easy if you have a degree in computer science and you’ve been working in IT for a few years. But for the average small business owner or accountant, not so much.

It’s not perfectly clear that the server is the glue between the database backend (which could be as simple as SQLite or as awesome as AWS RDS PostgreSQL) and the user’s actual experience in the client, which could be desktop software or a web browser. Some people don’t know what “client-server” means, let alone “model-view-controller”.

It’s also not clear, when exactly, you should setup your database. It’s actually left to the user to setup a PostgreSQL database somewhere, but that’s not immediately clear. Maybe just mention to new users that they should do this, and point them to a good Postgres installation/setup tutorial.

The following two commands should be very prominent, and totally exlained to new users. The first creates the tables in the database, which must first be created somewhere, and connected to… The second actually starts the web server, to which the client can connect.

  1. trytond-admin -d database_name --all
  2. trytond -c ./config.ini

The Docker Hub page with the Tryton images is also a bit cryptic. Just a few more sentences of explanation would save new users hours of head-scratching. Easy Docker container deployment can be a big selling feature of Tryton. Which brings me to my next point of Docker Compose.

Docker Compose is a very natural fit for Tryton, since Tryton is modular and Docker Compose links modular Docker containers together. @josesalvador shared this docker-compose.yml file with me, but I think a simpler 3-5 container setup would be very instructive to new users familiar with Docker. One container for Postgres, one for the server, one for the client, and maybe two more for internet deployment (Nginx and Certbot). Now that would be a quick setup.

Tryton also advertises that security is paramount, but how does one secure the server with HTTPS/TLS? Answer here.

I hope the above feedback is taken for what it is–the observations of a new user, struggling to get up to speed. Tryton is great, and the tech behind it is first-class too (Python3, Docker, and PostgreSQL). It’s actually the technology that attracted me, personally (plus the low cost).

Cheers,
-Sean

3 Likes

Thank you for this input.
I think we don’t talk about the same user. End user is not supposed to do system administration, imho.

For system administrators, Tryton technical doc is what is expected.
Can we help people to set a server if they are not skilled as system administrators ?"

There is not risk to make it bad if you just test fake data. But whatever you do, some will succeed and others will fail and get frustrated with Tryton, which is bad.
Then test solution might become production one in many cases. ERP is critical as soon as you expose real data in it, on an unsecured solution, which is worse.

This is why I set up a free hosting service of Tryton at https://sisalp.com. The user who needs a Tryton instance for tests gets it in minutes. It is fully secured and backed-up. It fulfills all the tasks you are struggling with and provides an immediate test bench.

Once going to production, the user can decide:

  • to stay on this free service forever
  • to buy from me an open virtual server co-administrated (me and the user)
  • to move to his own instance (with personalized help if needed).

return of experience shows a better rate of success on this do-it-yourself service than on a do-it-yourself documentation.

Hope this helps.

1 Like

At the risk of bringing this thread back on topic. :wink:

Having read the (very useful, enlightening and interesting) comments, I have also seen the proposal for Documentation on the proper place.

This proposal seems to me to be well thought out and sensible, and provides information about how the documentation should be developed and what format it would take. I think it could also cover most of the requirements for end user documentation?

Are there any other suggestions or proposals for what format the documentation should take, and how it should be developed?

1 Like

2 posts were split to a new topic: Tips for starting with Tryton