« HAManager: Design discussion, Why you need two JVMs to start an ND cell | Main | ObjectGrid as a high performance distributed data integration layer »

September 12, 2005

Experience with wiki for documentation development

We used a wiki for developing our design documents as well as programming guide for ObjectGrid. Twiki was the one we used. We set it up pretty quickly and there are a lot of plugins which we used to improve its capabilities. We linked it to our LDAP directory bluepages within IBM so everyone could use the existing intranet ids to login. It had good access control also.

For online documentation, it's pretty awesome. Noone had complaints in this regard.

For printed documentation, it could be better. The biggest complaint was lack of WYSIWYG editing. We used htmldoc to grab the html from the wiki and convert it to PDF. While HTMLDOC worked well, the process became a chore as we'd see a lot of warnings in HTMLDOC because java snippets on a topic were getting cropped off the page or pictures were too big etc.

Another problem was we use templates for our design documents and these are in Word format. No easy way to import these documents in to Wiki and later to export the modified pages as Word was also a point nobody liked.

Also, our sections became a concurrency problem as all check out/check in is page based and as the pages got bigger, we had clashes as multiple people needed to edit different parts of a page. Media Wiki is better in this regard as each topic is independantly editable of other topics on a single page.

So, overall, mixed. For online docs etc, it's very cool. But, for printed docs, I think it needs improving.

September 12, 2005 | Permalink

TrackBack

TrackBack URL for this entry:
http://www.typepad.com/t/trackback/3170649

Listed below are links to weblogs that reference Experience with wiki for documentation development:

Comments

I have used media-wiki on a large project for developer documentation. It was quite useful and well taken by the team.

Posted by: Prashant Rane | Sep 12, 2005 1:22:52 PM

We use Atlassian's Confluence - a wiki with knobs on. Its fantastic for managing documentation, especially technical documentation.

Posted by: Ricardo Sueiras | Sep 14, 2005 5:46:16 PM

Post a comment