Re: documentation for novice and newbies

[Andrei Popescu <andreimpopescu@gmail.com>]

CC'd to debian-user

On Wed, 7 Feb 2007 22:34:21 -0000
marc <gmane@auxbuss.com> wrote:

> Douglas Allan Tutty said...
> 
> > If we went with a wiki, we could have one long page for our project
> 
> What's the benefit of doing that?

I'm not sure what Doug meant by that, but I was thinking of a main
guide to be kept as short as possible, but full of references to more
detailed instructions/explanations/whatever. This way the reader can
decide for himself how much details he wants, something like:

[sample text]

To achieve task X you have to add abc to file foo and start foo-service
like this: /etc/init.d/foo-service start. More detailed information in
the relevant man-pages/web site/package docs (<-references to
existing docs), but we have also written a more friendly explanation
here (<-reference to our sub-page).

[/sample text]

> > with sub-projects as separate chapters.  We can follow the same
> > layout as a debiandoc e.g. release under GPL, Abstract, TOC, then
> > the chapters.
> 
> Chapters are good, but remember that you can use the tools to
> generate information dynamically. It's quite possible to include
> stretches of text in more than one section/topic/chapter/search
> result etc., while only having one source for that text.
> 
> The constraints imposed by thinking of online docs as paper books or 
> static HTML pages will create a lot of extra unnecessary work, I 
> suspect.
> 
> > Converting this to html is as simple as grabbing it off with a
> > browser and editing that to remove the "wiki" parts.
> 
> Wikis that I'm familiar with allow you to dump content to static HTML
> - and therefore any other format with a little work - as an automatic 
> process. Computers are pretty good at handling laborious, repetitive 
> tasks ;-)
> 
> Also, some wikis have "extensions" that will generate PDFs
> automatically also. You might also find a parser to generate LaTeX,
> which can be tweaked as required.
> 
> As a typical distributed, collaborative documentation project, it
> seems to me that a wiki is the best enabling technology, and
> providing you pick one that is easy to extend - or better, has all
> the extensions you already need, which is unlikely [particularly as
> you don't know what they are yet] - and easy to manipulate the data
> into other formats, you should be off to a flying start.

A wiki is definitely the solution. But it has to be as easy as possible
to add/change content (even without subscription?).

Regards,
Andrei
-- 
If you can't explain it simply, you don't understand it well enough.
(Albert Einstein)