[Advacs-discuss] Re: Documentation plan?

[David Palmer]

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

>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.
>  
>
Each of these levels of operation need to be catered for.
As I envisage the situation, as the programme itself is modular, it 
would probably be best if the documentation followed the same format. 
Any bridging work should be easily incorporated into the docs for each 
'add-on' module.

>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.
>  
>
What backup programme are we employing if we are actually including one?
Backup2l is one we could almost send out preconfigured.
Or is this something best left to the endusers personal choice?

>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.
>  
>
This I can get on top of.
As I said, the modular model is probably the one best followed here, 
allowing the enduser of that particular aspect of the programme to gain 
the knowledge that he/she requires, without being deluged with 
superfluous information that would only create confusion within a new 
environment.

>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.
>
A general overview to accompany the modular approach?

> 
>
>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 what I was referring to in a previous post with regard to 
skolelinux.
A header under the title of the module in the doc, describing the 
function of that module, how it goes about achieving its appointed 
function and how it fits into the overall operation of the programme. We 
could even html link this into the overview as previously described.

Why skolelinux?
To get an alternative to proprietary accounting programmes into the 
education environment, certainly, but further to assist in making the 
jump from classroom to school administration, and then further into 
government.
I'm still in two minds regarding this.

This approach would assist an accountant in a smaller operation to gain 
the knowledge to handle his own administration. which would negate the 
need for an external sys. admin overhead, and therefore potential for 
greater acceptance within the smaller business marketplace.
Documentation of this nature would cater for Helmut's idea also.

Or, it might be a case of 'too much information', and it would be best 
to make up a separate doc package for skolelinux after the main project 
is off the ground.

Comments?

>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.
>  
>
Yes, I mentioned man pages only because they are considered compulsory.
At my particular stage, for example, they're far to brief and obscure 
for the most part.
I see them as more of an aid to memory for somebody that already has the 
knowledge, or for somebody that has the knowledge and understands the 
vernacular.

Thanks very much for those pointers too, Oliver.
Much obliged.
I'm running sarge, and I noted 7.4.3-3 when I was downloading, so no 
problem there.
I'll get onto the rest of it very shortly.
Regards,

David.