On Sun, 2002-01-27 at 15:54, Mike Orr wrote:
> On Sat, Jan 26, 2002 at 09:08:51PM -0600, Ian Bicking wrote:
> > Right now a lot of the documentation is going into the Wiki, particular
> > works in progress. Maybe it makes sense to make more links from the
> > installation instructions to the Wiki. OTOH, maybe it makes sense to
> > put the entirety of the documentation into the Wiki, maybe making a
> > snapshot of it for releases.
> Wikis are really for a different kind of documentation than the manuals
> and READMEs provide. A manual is supposed to be like a book, e.g., big
> and with a fully-thought-out thesis from beginning to end, ideally
> covering everything the user might need. A wiki is more to fill in the
> gaps, especially for documentation that needs refinement or that changes
The two are different, and I don't think the documentation should be
written in Wiki style, but the basic technique of collaberation that the
Wiki allows might be beneficial. It would make it easier to add new
details as Webware evolves, correct errors, and in particular make links
from sections of the manual to places that cover aspects in greater
depth (like making other Wiki links). I say this, because as new points
are raised, they aren't (I don't think) being added to the main
documentation, but more often to the Wiki. I haven't looked at the
documentation for a while, so I don't know for sure. Anyway, while
stuff on the Wiki is generally hints, suggestions, and things not
entirely connected to Webware -- still, it's a vague line.
> It's definitely good to link to the wiki for things like the todo
> list, wishlist, troubleshooting tips, etc. READMEs on these topics
> would just go stale.
> Putting all documentation into the wiki brings up issues like the wiki's
> text-editing interface (bad for long documents) and HTML conversion
> ability (good for quick-and-dirty notes, bad for professional
> formatting, unless you put your own HTML tags in the document, which
> TWiki allows but kind of defeats part of the purpose for using a wiki in
> the first place).
> One counter-argument is that wikis are good for building documentation
> collaboratively, so one can generate content for an entire manual that
> way. That has to be weighed against, do you really *want* a hundred pages
> of manual material in the inflexible wiki format? You can do a basic
> conversion to another format programmatically, but there still would be
> a lot of manual reformatting aftwards for things the wiki format can't
> quite do.
This is a problem. Maybe TWiki and most -- all? -- Wikis aren't really
up to it. They aren't great at technical documentation, and the markup
is rather ambiguous. Oh, and web interfaces suck.
Now, with an XMLRPC interface... and Emacs happens to have an XMLRPC
library available... well, that could be a much better interface.
Still, the markup needs work anyway. Though using Zebra style
outline-mode HTML markup... well, at least Emacs users could be in
> > And if anyone wants to change the templates, I'm open to that. The
> > templates for TWiki aren't that great, but it might actually be quite
> > reasonable to generate them with Cheetah -- kind of novel too. It looks
> > reasonably simple to have alternate looks as well, which could be used
> > for snapshotting.
> I'm happy with the current template (header/footer), although if
> somebody wants to jazz it up, I have no objection. As long as they
> don't add a lot of slow-downloading graphics.
Actually, while it looks very much like the standard look for Webware, I
was thinking of making it just a little closer, which would just be a
little CSS and the removal of the image.
> What most deserves a reorganization is the home page. I'd move the
> most frequently-used links to the top left (especially the wishlist,
> todo, and the troubleshooting/HOWTO help topics), and banish the wordy
> parts (the intro and right column) either to the bottom of the page or
> onto a separate page. Perhaps have a "NEWBIES CLICK HERE" link so they
> can find their stuff quickly. The intro stuff and right column ppl will
> really only look at once, whereas the high-use links they'll probably
> use every time they come to the wiki, so it makes sense to have them
> show up in the first screenful.
> -Mike (Iron) Orr, iron@... (if mail problems: mso@...)
> http://iron.cx/ English * Esperanto * Russkiy * Deutsch * Espan~ol
> Webware-discuss mailing list