Call to arms: end user docs


(Eric) #1

i was not entirely sure which category would be most appropiate, please feel free to move if there is a more suitable one.

Whilst Tryton has matured over the past years its ‘end user documentation’ is as limited as it was half a decade ago.
Not only does it make things hard for newcomers, I also think it may be a major hurdle for general adaption in general.
Now, I do understand that this is not the first time someone brings this up (https://www.youtube.com/watch?v=dOumK2wqc-k) and I certainly do not underestimate the difficulties and effort required providing proper documentation tailed to end users but projects like django and others have certainly shown that good end user documation is a major selling point, community building tool and generally greatly appreciated.

Whilst I do not have vast amounts of time I am confident others run into similar issues like myself and together we may very well be able to come up with at least a basic steping stone for such a end user documentation:

What would be needed:

  • decide on a infrastructure/wiki. It seems the old tryton wiki is no more, so the question is if we should look for any generic wiki hosting solution or if the tryton project itself can/want’s to provide a way to house documentation (sphinx?).
  • It would be great if some of the more veteran tryton users would be willing to answer (from their perspective rather trivial) quesstions so that those answers can be incorporated into proper howto-articles. In the mid term this will probably save everyone redundant questions.

First steps:

  • Focus on several short articles describing how to setup a minimal environment (parties, sequences, etc). it will be important to find a reasonable balance between basic business/accounting concepts (which we can not explain in detail) and implementation notes on “how do i do X”. One thing that is sometimes hard from the outside perspective is to get a general understanding on how the various bits and pieces fit together.
  • After that we could move on to a module-by-module kind of approach.

(udono) #2

In the past there where a lot of attempts to write an end-user functional-documentation. But why there is no such documentation for Tryton?

Tryton is a modular system, so there are many limitations writing linear documentation texts. Such documentation could describe only a very specific setup of modules. Additionally Tryton is evolving very quick, It would be needed to follow the documentation for each version separately… There are many more reasons why it is better not to write user documentation.

But you are right, we need documentation for the application user. In https://discuss.tryton.org/t/how-to-write-tooltips we follow a slightly different, but IMHO highly practicable target: putting tool tips on every field in every model in every module. What do you think about this?