Re: documentation for novice and newbies

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


--
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
    ... CC'd to debian-user ... browser and editing that to remove the "wiki" parts. ... some wikis have "extensions" that will generate PDFs ... To UNSUBSCRIBE, email to debian-user-REQUEST@xxxxxxxxxxxxxxxx ...
    (Debian-User)
  • Re: documentation for novice and newbies
    ... I figure if we do plain ... easily mold that into any other format. ... You might want to check how the current Debian documentation is done. ... If we go with the wiki, then that fixes the file format. ...
    (Debian-User)
  • Re: Wiki-powered guidebook
    ... the data just isn't suited to the format - it is very flat and linear, ... The concept of a community-editable guidebook is a good one, ... I imagine an ADOM wiki would be pretty much a carbon copy of the ... information in a handy place instead of buried under piles of posts, ...
    (rec.games.roguelike.adom)
  • 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: Can you explain what this repo (yaml/Marshal) code do?
    ... def initialize(page_name, author, contents) ... let's assume you have a Hash of these things you are using to run your wiki: ... Writing them out is a pain though because page contents can be pretty much anything, so you'll need to come up with a good file format that allows you to tell where each revision starts and stops. ... you can load that back with: ...
    (comp.lang.ruby)