[Advacs-discuss] Documentation plan?

[Oliver Elphick]

On Sun, 2004-09-05 at 13:34, David Palmer wrote:
> I will get on top of it, but at the moment I'll be (slightly) more 
> functional with the docs. 
> 
> I'm working on html at the moment, and as each stage materialises I'll 
> forward it to the group for perusal/approval.
...
> I thought that I would do the main documentation first in html, as xml 
> can be nested within that environment, and things like man pages are 
> summaries of the main docs.

I think we could do with an overall plan for the docs, just as we are
trying to establish an overall view of the database before starting to
write applications for it.

Do you have any ideas about that?

I have imposed a de facto structure by language and module in the way I
set up the directories, but inside that, I should think we need to
decide how to target and structure the documentation.  More than in most
free software, the needs of users and of administrators are
substantially different.

There is the administrator who is setting up the database and needing to
know how to handle it for backup and maintenance.  His needs are largely
met by the PostgreSQL documentation and by the installation
instructions.

The administrator may or may not be the same person as the accountant
who is responsible for the whole system and needs to plan which users
are members of which groups.  The accountant needs to understand the
system from the accounting and financial reporting viewpoint.  He, or
staff under him, need to know which tables contain which data, how they
relate together and how the system is configured.

Department managers, such as sales ledger and buyer, may be separate
roles.  Such people need an understanding of their section of the system
and of the application programs that their clerks will be using, as well
as a general understanding of the whole system. 

Finally, ordinary users need to know how to do things like enter
invoices and journals and extract reports.  For many of them, this
knowledge will come from hands-on training, since they are likely to be
of the class of people who aren't able to learn things from manuals. 
Nevertheless, manuals and on-line help need to be available for their
trainers, if not for them.

The traditional manual page doesn't play a large role in this, since it
is unlikely that many users will be familiar or comfortable with that
paradigm.  Man pages should exist, but they will mainly be aimed at
administrators and trainers rather than end users and they will deal
mainly with the application programs, which we have not even started to
think about yet.

-- 
Oliver Elphick                                          olly@lfix.co.uk
Isle of Wight                              http://www.lfix.co.uk/oliver
GPG: 1024D/A54310EA  92C8 39E7 280E 3631 3F0E  1EC0 5664 7A2F A543 10EA
                 ========================================
     "He hath not dealt with us after our sins; nor rewarded
      us according to our iniquities. For as the heaven is 
      high above the earth, so great is his mercy toward 
      them that fear him. As far as the east is from the 
      west, so far hath he removed our transgressions from 
      us."     Psalms 103:10-12