I've decided not to look at the codebase until my iriver H320 has been
delivered, but that hasn't stopped me from jotting down a few ideas about the
* * *
1. Develop a new community attitude towards the wiki, and a culture of
recording information on it as soon as consensus has been reached in an
email/web/irc discussion. It should be seen as a cache for all the other
sources of documentation - you look there first, and if unsatisfied *then* move
on to the forums and tracker and mailing lists (and irc logs and code).
2. Archive forum threads once they've been wikified to everyone's satisfaction,
so they don't get in the way when you're browsing active topics or searching
for information that's NOT in the wiki.
If the useful-content-to-jabber ratio (which I've seen complaints about in the
IRC channel) still isn't good enough, then the categorisation/tagging of
threads could be tweaked to separate "which player should i buy" (support,
hardware) from other things. I haven't much to say here because I haven't read
too much in the forum. If interesting threads get clogged up with useless
drivel, then moderators could *hide* offending posts rather than deleting them
- viewers can opt to read them if they wish, kind of like a less democratic
version of slashdot's moderation system.
New threads that ask a question that's answered on the wiki get moved to the
archive straight away, and the poster gets sent an email with a link to the
appropriate wiki page. The forum software should make this a simple operation
(paste url or name of wiki page, then hit button or press enter).
3. Get rid of TWiki, use something much nicer (simpler), and make the namespace
hierarchical rather than flat. This would mean cleaner URLs (none of that
/twiki/bin/view/Main/ nonsense), no ugly and worthless CamelCase, and less
confusion all round. To give just one example of TWiki's inadequacy, it is at
the moment very hard to be confident that there aren't any useful orphaned or
obscure pages hidden away. The WebTopicList isn't any use - it's huge, even
after manually filtering out the pages in TwikiUsers.
Whether TWiki is kept or replaced by something already out there (or preferably
something written by scratch - I'd be *more than happy* to put a decent one
together), it should be easy to flag information as obsolete, dubious, or
otherwise disputed - a stale cache that hasn't been flagged as such is worse
than useless. A single click would be ideal, and automatically creating and
linking to a discussion thread for each accuracy dispute would be a nice bonus.
If editing privileges are restricted to trusted members of the community, it
would be great if unauthorised edits are not blocked, but auto-submitted to the
tracker as patches.
4. Install a bot in the irc channel that announces new discussion threads and
SVN commits as they happen. Maybe have it provide digests of other activity
(wiki edits, replies) every now and then. People who need support get quick
responses, and everyone is better-informed about what's happening in other
discussion media (I've noticed that people tend to stick to just one, which has
the potential to be a bit wasteful).
6. Integrate the wiki and the manual. I can see no reason for them to be
separate. I think I might have thought of a few reasons a couple of hours ago,
but if so I've forgotten them now. :)
PDF versions can be generated out of the box if the wiki uses reStructuredText
for markup, and conversion to PDF via tex/latex/roff is trivial if using
markdown or textile or something like that.
If the wiki stores its data in svn, then you can even have different docs for
each branch. Can't remember where I was going with that. Bleh, I'm tired.
7. Clean out ancient unused files from svn://svn.rockbox.org/rockbox/trunk/web
after making sure any useful info they contain has been wikified. Clutter is
* * *
P.S. Thanks for all the great work!
Received on 2007-01-11