Cash Flow report vs. Income Statement

[Derek Atkins]

Ken Heard <ken at heard.name> writes:

> What I have seen on line about Linux manuals, howtos, etc., pays great
> attention to the physical format of such documents, but very little on
> content format.  For instance before I start editing, I would like to
> hear from the code writers about the following:

In general I think the 'format' is significantly less important than
the content and content structure/layout/organization.  Whether the
content is in HTML, PDF, LaTexX, etc is mostly irrelevant.

> 1.  The purpose or objects of the GnuCash -- these are already stated in
> several places but could do with editing -- and the intended users.  One
> size rarely fits all.

Agreed, which is why we have multiple documentation formats.  There are
the developer docs generated by doxygen and online on 'code'.  Then
there are the Guide and Help documents, which are targeted at users.
The guide is supposed to be a step-by-step tutorial, whereas the 'help'
is designed to be a feature-by-feature description.

> 2.  Who are the intended audiences for the documentation.  There are
> likely several: the users and the code writers obviously, but even these
> two groups may be segmented.

I agree that there are two targets; I don't see any developer segmentation.

> 3.  From a discussion of 1 and 2, the content format can be developed.
> I can off-hand think of the following three documents, or groups of
> documents:
>
> a. A basic primer on double entry bookkeeping.

There are plenty of these already;  We should include the basics and
then forward users to the more in-depth documents out there.

> b. Howtos for the average 12 year old user. (I would use my 12 year old
> grandson as the prototype user.)

This is effectively what the guide is supposed to be.

> c. A reference manual for the code writers and advanced users.

This is the doxygen documentation.

You're missing the 'help', which is more about describing how a
particular feature works.  It's similar content to the guide but laid
out structurally differently.

> As discussions about the foregoing progress and we get to some pilot
> editing done, rearrangements of how the various features and options
> will be shown to be desirable.  A good place to start with such is the
> scheduled transactions tab, which I found very difficult to understand.
>  At this point what the editors find is fed back to the coders.

Difficult to understand as a user?  or as a developer?

IMHO the writers of the user docs can and should use the developer docs
to help them understand how the feature works.

However, there really are no dev docs for the UIs themselves, only
the underlying APIs.

> Please remember to CC this list on all your replies.
> You can do this by using Reply-To-List or Reply-All.

-derek

-- 
       Derek Atkins, SB '93 MIT EE, SM '95 MIT Media Laboratory
       Member, MIT Student Information Processing Board  (SIPB)
       URL: http://web.mit.edu/warlord/    PP-ASEL-IA     N1NWH
       warlord at MIT.EDU                        PGP key available