Re: documentation for novice and newbies

[marc <gmane@auxbuss.com>]

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?

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

All FWIW.

-- 
Cheers,
Marc