Improvement on the official documentation

It will be great to complete the official documentation with the common user workflows that you think are missing. While we do not want to provide screenshoots for the documentation, probably there is some room for improvement on the oficial documentation and it will be great to fill the gap.

Hi @pokoli, if I was just hired as as a junior purchaser by a company using Tryton and wanted to understand the purchasing “big picture”, how do you envision I would find and access this information? E.g. where would it fit (or how would it integrate) with existing documentation? I am not asking as a critique, only to understand your vision (also please say if this is your personal vision, or if this is the vision of the project team and/or foundation).

Imho, the documentation on tryton.org (https://docs.tryton.org/en/latest/) is of most use to developers and advanced users (people already familiar with ERP software in general and just need to understand some Tryton specifics), and is not basic enough or detailed enough for entry-level users. However, I do not think there is necessarily anything wrong with this. Using Tryton is complicated and takes effort to understand, and it is neither practicable nor desirable for the project team to try and be all things to all people.

Could you elaborate on how Tryton user training typically happens? My understanding is that you are not only a Tryton developer and member of the foundation board of directors, but also a provider of Tryton implementation and related services. How do your clients (and more specifically their employees) learn how to use Tryton? E.g. Do you (personally or Kopen Software) provide training sessions and documentation? Do you train a client “power user”, or does the “power user” train themselves, and then they train the other users? (the “train the trainer” approach?).

By the way, I found the Managing Gift Vouchers post on Kopen very informative - and coincidentally another example of how training is provided. :wink:

Personal vision, @ced is the only one deciding the vision about the project code/documentation.

I shared the module tutorial with an new developer some months ago and I had the same feeling.
If you think the same happens for user documentation there is a lot of room for impovements IMHO.
It should be considered that we always had the forum as last resort for explaining tryton to its users.

At Kopen Software (the company I work for) we usally do all the user training using videoconference. We also have published a tryton online academy with the idea to make this training available for anyone interested.

Thansk for apreciating our work. We try to share use cases and some small tips about tryton modules usage. Normally this is based on feedback and requests for our customers. But as 90% of our audicience is in Spain we publish it just in Spanish. For now we do not have the resources to publish it on both Spanish and English, maybe in the future, who knows.

1 Like

We always consider that readers are familiar with the common notions of ERP.
We do not have the resource (and it is probably not the goal of the project) to provide general documentation about running a business with a software.
Maybe we could identify some existing general resource about this topic and add a link. Or just put statement about the prerequisite to read the documentation.

Imho that is a very reasonable position, and it also defines the “market” for Tryton from the perspective of the Tryton project (and I presume also of the Tryton Foundation). IIuc, traditional customers of Tryton developers, and of service providers who are also developers, are experienced ERP users who understand the costs of commercial proprietary ERP systems, the cost of achieving their needs using a commercial ERP system, and the value of achieving their needs using Tryton.

However, it seems there are members of the Tryton community (myself included), who believe there is a market of less-experienced ERP users (in my case, hardware startups and manufacturing SMEs struggling with the likes of QuickBooks(R) and spreadsheets for BOMs and “master production plans”), who could use Tryton if they had more support. Hence my writing Working with Tryton (which I will readily admit was initially influenced by Working with OpenERP by Greg Moss, published 2013 by Packt Publishing).

Personally, this feels very much like the FreeBSD and OpenBSD projects, which provide basic technical documentation (e.g .the FreeBSD Handbook), and authors in the community such as Michael Lucas provide books for less-experienced users.

2 Likes

Creating new forum topics which documents a business process in Tryton should automatically become an addition to the appropriate tags in the documentation.

My vision is to have one tag for each functionality named in the functional documentation overview. In each functionality section (e.g. accounting section) in
the documentation we have a prominent link to the tag in Discuss.
It would be great when we also can show automatically the 7 top new/rated/read topic headlines of the tag.

And vice versa each category in discuss is back-linked to the appropriate functionality section in the documentation.

This way we can quickly add user documentation, Tutorials and How-tos on demand and on availability.
We would be able to collaboratively edit and discuss the content easily.
Additional tags or categories could be used to select topics to include or to filter out topics for older Tryton versions or topics needed to re-work.

NB. We also talked about a similar idea in the Maintenance Slot in Tryton Unconference Berlin 2023.

WDYT?

Edit: Replace categories by tags

I do not think creating more categories is good for the forum.
Indeed there are tags already used for that.

I think we have already a place for every topic in the documentation. We are just missing the volunteers to make the edition.

oh, I mixed it up, sorry. I corrected it in my initial post.

Yes, but I think with the actual sphinx setup there is an entry barrier for writing documentation, asking related questions and giving feedback or corrections.

We already have a low level entry point for user documentation but it is not connected with the other documentation.

Yes, but IMHO because the volunteers are required to handle mercurial, code-review cycle, restructuredText and our guidelines.

For me it makes no sense to try to solve writing documentation and asking question at the same time. These are not the same at all.

The howto category is not about low level entry. It is about documenting some process that are cross modules (so they can not fit in any module documentation).
Writing there is restricted and should go through review process on Draft Howto - Tryton Discussion

Yes we want review to ensure quality. Wiki style documentation become obsolete just after pressing save.
Any way I feel that the same complaint about the workflow is made again and again no matter what improvement or simplification we put in place. We moved from patch to rietveld, then to heptapod; we added reviewbot, then CI and lint; we added edit button on the documentation page etc. But still the exact same complaint is made over and over. So for me it is clear that it is not about the tooling, it is just the lake a willing to contribute.

First, I understand what you mean, but also what @udono means. So I want to propose a few changes with the main goal to make it clear to the users what to do when they spot some typos or want to make changes to the documentation. Generally it kind of ‘separates’ the documentation from the code.

  1. I haven’t tried the online editor in heptapod, but when users can use that functionality for documentation, will be a big win. They don’t need to clone the repository and do things they don’t like. Question is, will this work with how the repository is set up etc.

  2. Add a section on the ‘contribute’ page on the website. There is a section about submitting changes, but I also think something like that should also be there for documentation and mention specifically the online editor and tell how the workflow of documentation goes. Maybe duplicating text, but it’s way more clear and more specific. Some users want to contribute writing documentation but don’t find specific information about how to start.

  3. Make clear what kind of documentation you expect. For example I installed and configured SAML with ADFS and want to create a small document to walk you through the setup and where to look which means talking a bit about PySaml. Is this kind of tutorial allowed to get in?

  4. The edit button on the documentation itself is hidden in a mouse-over popup. Maybe it can be always show near the search or fullscreen button. BTW, the ‘suggest edit’ doesn’t work and gives a 500 error on heptapod.

It is a frustrating for me to read this, especially the last sentence. I am sure there are lacks in the project, but I really can’t see a lack of willing to contribute.

I was not talking about the

or

which are a great help, but another topic.

I was talking about @dalers questions on writing native english Tryton documentation for end user related problems. And he thinks loud about how it could possibly be re-used in the Tryton-project,

I also think this kind of user documentation is,

So why not putting such documentation into howto-discuss-category as separate topics.

My (only) proposal is to add links in the sphinx documentation to topics in the howto-discuss-category and linking from the howto-discuss-category back to the user documentation. At least to make each other more visible.

I am also fine with

This is not targeting you (sorry if it seems to). But I must say that I feel there are not a single on this forum without having someone complaining that he can not contribute because something is missing. Personally this is very annoying and demotivating.

As you were referring to the Maintenance Slot I do not really understand what you want.
I think it will be clearer if you can propose a merge request.

For me it seems to work but I can not really test in real condition as I’m administrator of the project.

For me it sounds too much specific. This is closer to a blog post than a documentation (I think I already told you that the LDAP module documentation may be improved if something was missing).
Maybe we need a new category for message board from the community. I will start a new thread for that.

Yes you already told that and I’m going to propose some changes to the documentation. And I’m going to use the online editor for that.

Thanks!

It’s really hard not to LOL here. Many people tried to contribute (me included), but in >90% of all cases we were rejected, discouraged, ignored. For me, this was so frustrating that we published our “Tryton-Buch” in German, on tryton-dach.org. It could have been English and on tryton.org - but all the authors did not see any chance for that.

This is your overall mantra. And only YOU know what quality is - everybody else is an idiot. Such we’re are feeling

Sorry, I need to call that pure nonsense. Mainly because you draw the consequence to rather have no user guide and plunge 98% of potential users.

A wiki docu would not be my favourite solution, but most IT users could easily contribute. You nerds are familiar with a little nerdish tools like git, hg etc. Users normally are not. Therefore, it’s not a miracle that hardly anybody wants to contribute.

And there is another prove that valued Mr. Cédric does not want user docu:

I suggested to include external user docu (such as German Tryton-Buch, but as well pieces in other languages which certainly are there) into tryton.org here. This would greatly improve Tryton’s accessibility by hardly any effort. Of course, valued Mr. Cédric rejected this proposal.

I resigned from trying to do docu on tryton.org, I’m now doing it on tryton.community and I hope, that on the long run that will evolve to THE major of information for users.

I think this is a clear opportunity to make you both happy.

@herrdeh using the heptapols tools you will be able to contribute to tryton oficial documentation.
@ced will you like to mentor @herrdeh and explain him the requirements to extend our documentation?

@pokoli ,thanks for keeping so constructive in this challenging environment.

Sorry to say this, put I’ll not follow your proposal for these reasons:

  • I’m strictly against our software architect and -engineer in-chief wasting his precious time with such child’s stuff;
  • time passed by over this. I’m now committed to tryton.community and will try to get things forward there.

I do really belive that if we all keep constructive we can achieve better results. My effort follows the wish to have a single source of truth in terms of documentation.

Having said that I can not avoid you to decide where your work is published. :man_shrugging: :man_shrugging:

We have a trainee at B2CK and we ask him to follow the tutorial to make and propose improvements.
So he made his first MR using the online editor: Clarify the need to create the opportunity.py file in the tutorial (!986) · Merge requests · Tryton / Tryton · GitLab
The point is that you need to update the Target branch to starts with topic/default/… as explained in Editing files through the web and creating merge requests and topics - topic name (#329) · Issues · heptapod / heptapod · GitLab

Wow, please live stream that on some online platform so we call all learn/help him! :star_struck: :star_struck:

Our last trainee ended up using the coopengo tutorial because it clarifies better the concepts. Maybe that helps him also