Question

I’m running into a situation, common I’m sure, where my business rule documentation is spread across emails, documentation (now out of date) and IMs. This stinks.

I can think of 2 alternatives: Sharepoint (hate it, the search feature is terrible) or a wiki.

Some things that I’d like to see in the ideal solution:

• Easily updateable: don’t make me pull up Word to update the docs
• Diff view: Sometimes you only need to see what’s new
• Subscribable: Notification of new changes on a page by page basis
• Role based: Editing and viewing of pages can be tied to roles
• Attachments: Easy inclusion of mockups, files etc.
• Search: It’s a post google world, I want to be able to search and find instantly — Sharepoint loses in this category, unless the one we use is configured incorrectly
• Attachment Restriction: Ideally, the solution would not allow uploading of a bunch of Word docs that we’d then call our documentation. I’d like the documentation to have a consistent (and simple) format. Enforcing attachments as PDF, txt and so on.

Following up on my wiki comment it looks like there are at least 3 wikis that do what I want (Incentive, SharePoint-Wiki-Plus, ThoughtFarmer). ThoughtFarmer, love that name.

Answer 1

+10⁶ for a Wiki, it’s the best solution I’ve found so far for documentation, especially technical documentation. IMO, the advantages of “good” Wiki engines over Office documents in a VCS are (but you’re already aware of that as this features list is very close to your requirements):

• they are just faster and easier to use than Office documents in a VCS (no need to open the VCS client, checkout the latest version, optionally lock it, open word, save, check-in, release the lock)
• they are text based so you make diffs (unlike word) and this just a must have
• they offer notification mechanisms (e.g. mail, RSS) and so the information is pushed to you (unlike a VCS where you need to pull document when they are out of date)
• there is no “document locked by another user problem” because someone forgot to release it (if you are using exclusive lock which is often the case on documents that you can’t merge)
• pages can be easily refactored, reorganized, assembled in bigger documents
• they are really collaborative
• they provide much better support for code (e.g. you can point directly on the source code in a VCS with much better formatting than in word)
• they can index the content of pages and attached documents (pdf, office docs, etc) and make it searchable

The only issue I’ve faced when using a Wiki for documentation is that it’s harder to version your documentation in the same time as your code (i.e. you deliver version x.y.z and want to “lock” the documentation of this version). I’ve used exports to solve this but it’s not perfect.

I’ve already worked with TWiki Foswiki, Confluence and XWiki. They are all “good” Wiki engines (as defined above) and all meet your requirements. So the final choice may just depend on your constraints (license, pricing, technology) and personal preferences.

As of today, I’d choose Confluence if a commercial tool is an option, XWiki if not.