CC'd to debian-user On Wed, 7 Feb 2007 22:34:21 -0000 marc <[EMAIL PROTECTED]> 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) -- To UNSUBSCRIBE, email to [EMAIL PROTECTED] with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
