Re: documentation for novice and newbies
Douglas Allan Tutty said...
> Answering this myself, it seems that wikis are flat in that all pages
> are under the one main wiki, but any page can reference any other page.
It depends on the wiki. I use PmWiki[1], both as a wiki and a
development platform for web apps, and it has a number of ways to
organise pages. At the top level are groups (you can use just one, if
you wish). Organisationally, this is useful, but it also allows searches
to be constrained to a group, which is very useful.
There are other mechanisms. For example, you can tag a page as being in
a 'category'. You can then display the page for that category and see
all related pages.
This is just the tip of the iceberg, though. As I mentioned elsewhere,
it is incredibly limiting to think of data in terms of a book (flat)
when mining data from a wiki.
For example, you can 'include' text from other pages (by page, by
section, or line numbers).
> However, if we went with multiple pages, scraping it all off and
> combining it into a stand-alone html doc could be a problem.
This is a routine procedure for many sites[2].
> A couple of problems with using versioning/docbook, that probably have
> solutions but I'm unfamiliar with both: I'm on a slow dial-up line.
> With versioning does that mean that I grab the current version, download
> it which locks others out of grabing it, edit it, then upload the new
> version? That cycle could take a while and tie up the document.
Updates are simply diffs, so very small, even for dial-up. And no, no-
one locks out anyone else unless a manual lock is applied. (I'm thinking
Subversion here.)
That said, wikis usually provide their own versioning, and some provide
draft facilities. (PmWiki has both, for example.)
> I _think_ that a wiki makes this a lot faster. It allows us to generate
> html. However, it makes it difficult to break it up into small
> documents and link them together again, and to make other formats.
This really isn't true. (Not getting at you, but this looks like a
domain that you don't have much exposure to, so how could you know :-) )
--
Cheers,
Marc
[1] http://www.pmwiki.org/
[2] http://www.pmwiki.org/wiki/Cookbook/ExportHTML
Reply to: