[Advacs-discuss] Documentation plan?

[Helmut Wollmersdorfer]

Oliver Elphick wrote:

> 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.

ACK.

> 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.

Let's call him the db-admin.
Additionally he would need information about the db-design, modules, 
hooks, interfaces etc.
I assume, that most of the potential users of ADVACS will still use 
another ledger, and will need to migrate their data from the old ledger 
to ADVACS. For medium companies this will need some scripts, to get e.g. 
customer/supplier data or open items to the new system, if we do not 
support standard interfaces for this. The admin will need all the 
necessary information to be able to script this.

> 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.

Usually, between the db-admin and the simple user, there will be 
somebody, who organizes the account structure, maintains user 
permissions, configures options etc. Let's call him ADVACS-admin.

> 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.

This is the user manual, which describes all functions.
Additionally I see a demand for novices, to have the basics of a ledger 
explained - an accounting tutorial.

> 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.

ACK.

Helmut Wollmersdorfer