discuss: GUIDE in Wiki, example of the LVM-HOWTO
Subject:
Re: [discuss] GUIDE in Wiki, example of the LVM-HOWTO
From:
David Lawyer ####@####.####
Date:
18 Dec 2008 08:34:41 +0000
Message-Id: <20081218082532.GG2205@davespc>
On Wed, Dec 17, 2008 at 01:21:41PM +0200, Svetoslav Petkov Chukov wrote:
> I agree,
> Actually I think we should reconsider the type of the documents.
>
> HOWTO - A document that describes information how one can achieve specific
> task, result or target. So, the document should be more like a step-by-step
> approach.
> The document could be in the following basic structure:
> - do that.
> - execute that command
> - run this script
> - etc...
Any document that fails to explain what is going on (theory ?) is
going to rapidly become obsolete as software changes but the "theory"
remains the same. So the name HOWTO is a misnomer for the better
HOWTO's that explain what is going on. But since the word HOWTO has
been around for a long time, I think that it should be kept. It
should present the theory first, and then give some examples of it's
step-by-step use, explaining what each step is doing and why it's
needed (perhaps not explicitly). This is done is some computer
textbooks, such as the ones by Tanenbaum.
> -- additional information, history and some technical and theoretical
> information.
>
> GUIDE - A document that discuses information about specific topic with more
> than one step-by-step approach or includes more complicated and mixed
> information about other topics.
> The document could be in the following format:
> - information about the topic 1
> - information about the topic 2
> - information about the connection between them
> - etc...
> -- additional information, history and some technical and theoretical
> information.
In LDP a Guide was about the same as a HOWTO, only longer.
>
> TUTORIAL - A document that contains several GUIDEs or HOWTOs.
This is not the common meaning of "tutorial" which means something
that is written to teach someone the subject, sometimes repeating
information to help one learn it.
>
> I really think we should have a look about that definitions. The whole
> documentation repository is based on them. So, we should define the
> documents not because of their size but there basic structure. If a
> particular document matches a target structure then it should be qualified
> by that structure.
I don't agree. Furthermore, LDP is unlikely to have the volunteers
available to determine the structure and there are all sorts of
different structures. Docs just don't neatly fit into one structure
or another.
David Lawyer
