On Fri, 2011-03-25 at 08:38 -0700, christym wrote:
> I've installed Tryton easily. However, out of the box, it is useless.
> It has to be configured for the business that wants to use it. This
> is far from being intuitive . The default screens that pop up the
> first time Tryton is opened after installation, are intended for this
> purpose. However, since most fields and buttons, have names made up of
> a single word, they are completely ambiguous. Who knows what the
> designer intended the field or the button to be used for?
>
> I've searched the documentation for a configuration guide but none
> exists apparently. The documentation that is available is extremely
> nerdy, focussing on things programmers might want to know, not the
> things an accounts department wants to know in order to delegate tasks
> to accounts staff. Does a set,up & configure manual exist for
> accountants to use?
>
> If not, and if no one is available to write one, could I suggest you
> at least put explanatory bubbles containing this kind of information
> in place, to pop up everytime the cursor hovers over the button or the
> field.
>
> Regards
> christym
>
You are absolutely correct. This is an issue that I raised in IRC the
other day.
I have a client who is in need of an ERP driven solution, and Tryton is
a great fit on all counts (including licensing and development model).
The main problem is the lack of documentation (the other problem is more
mundane: lack of a Japanese version; but we are translating it ourselves
currently).
For enterprise systems we typically depend on three levels of
documentation:
1. User end documentation. This is for Joe who has to go to work
every day and actually use the system to get work done in the
real world. The system should be a tool of the uncluttered
utility for this type person and the manual should describe, in
functional prose, how to get actual work done. The system
should, in turn, behave precisely however the manual says it
will.
2. Administrator documentation. This is for the person in the
company who gets trained on how to do things (in the case of an
ERP system) like create users, adjust or create workflows, edit
the formatting of dashboards and invoice printouts, and other
related internal administrative tasks that are too trivial or
routine to be outsourced to a services company.
3. Developer documentation. This is for core developers, module
writers and servicing companies who need to know the internals
of the system in order to write customized modules to suit the
unique needs of different business types.
Tryton almost entirely lacks categories 1 and 2. I don't think there has
been much discussion yet about clearly identifying the need (or even
categorizing these by type) for this sort of thing just yet. Tryton is
used primarily by its core developers at the moment, and was until just
recently still in its budding phase. That being the case, Tryton is
replete with the 3rd sort of documentation.
But Tryton is now past its creaky beginnings and, in my opinion, ready
for some real world use. That means we suddenly are in desperate need of
a real documentation project to address the user and administrator
level.
You noted that "out of the box" Tryton is useless -- and it is. One very
important type of documentation lives far beyond the manual, and that is
in example test data, in-session tool tips, comfortable templates, and
core dialogues (i.e. wizards). This base use data is something that will
definitely need to be not only created but also bundled with the core
Tryton distro. Ideally, commands such as "yum install tryton" would not
just install the Tryton core, but all the modules that are considered
official parts of the central project (disk space is cheap -- why make
it complicated to get another few megs of highly useful data?) in
addition to complete user and adminstrator manuals installed to obvious
locations, GUI menu additions (i.e. Gnome Applications->Office->Tryton),
and a set of system test and example data which comes bundled with each
module (and relevant to only that module).
My intention is to perform the customization necessary to get Tryton
working properly for the accounting division of my current client.
Obviously this will entail a lot of on-site customer training and the
majority of materials that will come out of those sessions will be in
Japanese. Once I've gotten that far, however, I will be engaging in a
very deliberate effort to translate that to English written and edited
by native English speakers (I have technical editing experience in
English and Japanese -- but unfortunately there is only one of me, so
this could get slow).
I firmly believe that the fruits of this effort will catapult Tryton's
user base far beyond what any additional modules or features ever could.
In fact, adding more modules or features right now would be counter
productive to the goal of growing the Tryton user base (as distinct from
the developer base). Adding more features and modules will only add more
undocumented complexity in the eyes of newcomers, and drive them away
from the scary logical explosion they would have to privately make sense
of with no external aids or community.
So... I've announced my intention and goal. Anyone who would like to
join me in creating an English-language documentation project is
welcome. To that end I recommend that we create a work space somewhere.
Wikis are great for this, so long as we remember to keep it organized
and adminster it in the same manner, say, a WikiBooks project works.
This means structuring the wiki very carefully, remembering that a good
manual is a linear set of text with a clear beginning, middle and end.
It must be a story for the user to follow, not a pile of independent
essays on separate features. This stands in contrast to a blast of
disparate documents with no clear path for the reader to follow. This is
the trap that developers often fall in to when trying to write user
documentation -- because development is inherently chaotic and scattered
and developers are comfortable with that. A developers intimacy with the
code and the system makes the "pile of papers" workable, a new user's
complete lack of initiation makes a clear story arc to the manual
critical.
I am hereby volunteering to lead the effort. Administratively speaking I
don't know if it is simpler to start a semi-separate project to keep the
Wikis independent (which may be a good idea -- after all everything
being hypertext anyway they can still link to each other across sites)
or if Google provides good enough tools to allow a clear branch within
the existing wiki to emerge.
I also do not know if the existing Google wiki would make it easy to
extract the wiki text into a user-deliverable package for distribution
as a searchable/indexable help file, or if packaging PDF manuals and
help files based on Google wiki text would involve huge amounts of
brainless copypasta work every time a new version comes out. Extracting
wiki text without an automated tool is a big enough pain in the ass that
this really should be the deciding factor.
Your thoughts (directed at everyone)?
-Iwao
--
tryton@googlegroups.com mailing list
