Documentation: open user invitation to help out

[Mike or Penny Novack]

Geert Janssens wrote:

>We just had a lengthy thread on report customization. Some of you may have 
>followed it, other may not.
>
>One of the things in this discussion that caught my attention was that reports 
>are hard because of a lack of documentation. This is not only for reports, 
>this is true for several areas in GnuCash.
>
>So this is a general request to users (and developers who are usually users as 
>well), to help and improve the documentation.
>
>This is not hard to do. All of you can help out at some level. It only takes a 
>little of your time.
>  
>
ABSOLUTELY.

What is the issue here is the difference between a "manual" and a "user 
guide". The former tells you how to use the application at one level; 
the latter at a very different level. The former tells you things like 
where you get to select options for reports and perhaps how to do so. 
The latter tells users "if you want THIS type of report you initially 
ask for THAT report (relationship not necessary obvious to an accounting 
novice) and then change the options to ......... and export the report 
and edit away ...."

By and large most free software projects, while they may have a decent 
"manual" do not come with a "user guide". Note BTW while it would 
possibly be wrong to create an unfree manual for a free software 
application it would not be in the least wrong for somebody to create an 
unfree user guide ("Application X for Dummies" book for instance). But 
it would be NICE if we could put together a user manual to go with 
GnuCash and that could/should include a useful bibliography for texts on 
bookkeeping/accounting basics.

As for "the user is always right" that's nice for CYA (you can't be 
BLAMED for doing exactly what the user asked for and signed off on) but 
that's the analyst not doing his or her complete job. To do it right the 
analyst makes the effort to recognize and then explain to the users so 
that they can understand "what you are asking for will NOT give you what 
you think it will" and "what you are asking for is unsafe and sooner or 
later will bite you". To do that the analyst has to question the users 
until he or she understands their business needs (and then can make 
suggestions about the best ways to satisfy those needs). It usually 
leads to trouble for the user when they both specify their needs AND how 
those needs could be met. Users are trained to do their jobs well, what 
they get to see every day. They simply don't ever think about the "rare 
cases" that would make a method blow up and that is reasonable on their 
part because as an individual user, they might only see one of these 
rare cases per decade, only a few in their entire working career. But 
that would mean in a system of 100 users one blow up per month!

Shall we organize a "manual team"?

Michael