Re: [GnomeMeeting-devel-list] Manual

[Christian Rose <menthos menthos com>]

lör 2003-02-22 klockan 15.05 skrev Niklas:
> This is all starting to scare me a little bit. The reason to why it
> scares me is the talk about manuals,FAQ and things like that.
> 
> Some things I don't really understand why some people do not understand
> are the differenses between the FAQ,manuals and docs.
> 
> AFAIK
> 
> FAQ section is just direct answers to questions that has been asked many
> times either on the list or in other mails. Maybe even IRC. But the FAQ
> should not really contain anything else more then direct answers.
> Example:
> Question: What is gnomemeeting?
> Answer: GnomeMeeting is an H.323 compatible videoconferencing and
> VOIP/IP-Telephony application.......

This is correct. FAQs should ideally be kept as short questions with
short answers.



> Manuals should not be explained with every little detailed information
> because if you look at a manual you want to know. It should be small but
> still useful. (Hard to explain) 
> 
> 1. How I start using the application.
> 2. Small examples of how to run the applikation in different ways.
> 3. Parameters for the use of gnomemeeting.
> 
> Documents are more detailed with information and can be changed from
> time to time. A document can have both html,pdf and txt versions and
> should be converted from a makefile. A document contains sections of
> usage for the different parts of the application it explains. The FAQ
> could be build this way...yes...but documents are more likely to have
> the sections then the FAQ. But the size of the document depends a lot on
> how you want to write it. (Book or Article)
> 
> So my question now is: Why is this all a trouble?
> 
> Manual:    Short with good information of usage of the application.
> FAQ:       Directly answered questions without subsections.
> Documents: Contains more "in detailed" information about the application
> and is the one most likely searched for on the site.

This distinction I don't agree with. Typically real physical manuals are
divided into chapters and first have a short introduction for basic
usage, but then they go into finer detail and document details. AFAIK,
we don't have the manual/document distinction you describe otherwhere in
GNOME user documentation. Developer documentation is another issue.

I suggest moving this and similar discussions on documentation-related
matters not directly related GnomeMeeting to
http://mail.gnome.org/mailman/listinfo/gnome-doc-list/, as the people
there have heavy experience in writing manuals and also can help with
questions on organization, etc.


Christian