Re: documentation for novice and newbies

CC'd to debian-user

On Wed, 7 Feb 2007 22:34:21 -0000
marc <gmane@xxxxxxxxxxx> 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 debian-user-REQUEST@xxxxxxxxxxxxxxxx
with a subject of "unsubscribe". Trouble? Contact listmaster@xxxxxxxxxxxxxxxx

Relevant Pages

  • Re: documentation for novice and newbies
    ... and editing that to remove the "wiki" parts. ... and therefore any other format with a little work - as an automatic ... some wikis have "extensions" that will generate PDFs automatically ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ...
    (Debian-User)
  • Re: size of wiki.debian.net
    ... >>Hi Raju, ... > The way I am currently using the wiki is as follows: ... If every user posting to Debian-user does ...
    (Debian-User)
  • Fw: Katherine or Catherine de Beaumont and her parents??? 16th century
    ... Any project like this needs to be a Wiki. ... antiquity to medieval ancestors likewise? ... To unsubscribe from the list, please send an email to GEN-MEDIEVAL-request@xxxxxxxxxxxx with the word 'unsubscribe' without the quotes in the subject and the body of the message ... No virus found in this incoming message. ...
    (soc.genealogy.medieval)
  • Re: documentation for novice and newbies
    ... so we can't get the debian ... If we went with a wiki, we could have one long page for our project, ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ... Trouble? ...
    (Debian-User)
  • Re: documentation for novice and newbies
    ... and also webpages (wiki or not). ... Andrei ... I just went and looked at this for the first time. ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ...
    (Debian-User)