Article:  |
Splitting Books Open: Trends in Traditional and Online Technical Documentation | |
| Subject: | Wiki as documentation | |
| Date: | 2004-09-29 03:23:56 | |
| From: | scottwalters1 | |
|
Thanks for this excellent article. You suggested traditional publishing and informal publishing might cross paths. Well, that's exactly what I've been working on (for one of my many projects) for the past few years. perldesignpatterns.com hosts a collaborative effort to write about software design using Perl. You also suggested ways forums should opperate. I'm happy to report you've given us a good store. Pages may be voted on. A table of contents is used to construct a book-structured document by way of an "expand links in place" script, the result of which may be saved to disc. Other pages may use the same script to create custom "light" views of the manuscript. It's heavily cross referenced. RSS feeds and comment boxes (less threatening than Wiki's "edit this page") attempt to foster community. Documentation on other sites is indexed (in the past, the Wiki has even automatically back-linked, but this is fighting with the RSS feeds and search engines, so it's offline for now). On the non-technical front, pages are contributed by people in their spare time (including myself). Each "page" (somewhere between a chapter and an actual page) has a narrow scope, and may be as technical and specific as necessary. Like a dead tree, it's fully outlined. Any important topic not covered is at least a footmark making the readers aware of the missing information. In-line VisualizationCompilerGraphs markup renders to png diagrams on the fly, giving authors the ability to create diagrams (something quite often lacking from forum discussion). In the interest of letting writers meld the Wiki to their needs, Perl may be included in pages to be run on the server side where it runs in a sandbox, able to read other pages, and write to the current page or any page with 'Public' in its name. Most of the site features, such as the Patterns Index, use this. Or perhaps I got a bad score. Rather than being the best of both worlds, in many way, it's the worst. It needs an editor. The quality is poor. It's not being kept up to date as well as it should. The community dynamics haven't taken off (yet). People don't feel like they really can voice a dissenting view, or even that they have any sort of ownership over anything on the site. People not used to Wiki get lost (not for the lack of "normal" navigation but more for the inclusion of Wiki navigation). Some chapters are rough. This didn't happen by accident. I brain-stormed on what I liked about printed books (editorial influence scored highly, but comprehensive treatment is also important) and what I liked about forums (PerlMonks and WikiWiki have killer community dynamics that have developed a breadth and color a single author couldn't hope to acheive. I need to return to this project from something else I'm working on (hint: it's yellow and black, yuck), but I plan to hire an editor and then shoot for a dead tree edition (GNU Press has expressed interest). I'm sorry to toot my own horn here, but I think the subject is really interesting, and I really like talking about it ;-) (I'm a total zealot, ask anyone.) Best wishes, -scott |
||
