What's a good solution for collecting business rule documentation?

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.

Answer 2

Drupal meets your listed requirements, it is highly extensible with loads of modules (see some below) and it's available under GPL.

• Wysiwig editor
• Diff view
• Subscriptions
• User access management
• Attachment management
• Can be configured with Wiki functionality

Answer 3

I am developing one.

About a year ago I looked for requirement management software on the 'net and found at least 30 of them, in approximately 3 categories:

• Priceless (and marketed e.g. at aerospace companies)

• Expensive (e.g. $1000s per seat), which my employers have never chosen to use

• Cheap or free, but missing features which seem to me important

There are also general-purpose tools (e.g. Wiki, or emails and Word documents and/or Spreadsheets), which too are missing features which seem to me important.

---

I think you should elaborate re: "are missing features which seem to me important".

There are things which you can do with a general-purpose Wiki:

• Create a list of features
• Describe each feature (perhaps a separate page/section for each feature)
• Do this collaboratively (version control, update notifications, discussion pages)

But, there are some things which I think you can't do with a general-purpose Wiki, even pretty basic things:

• Define custom attributes (e.g. "Date started", "Estimated cost", etc.); associate these attribute values with your features; list features (in a table or grid) with their attributes (so that they can be sorted, e.g. sorted by "Importance" or by "Difficulty")

• Help with traceability (traceability not too difficult when there are only two stages, e.g. "requirements" and "implementation"; but it's harder when there are several stages, e.g. "use cases", "functional spec", "architecture", "implementation details", "test cases", "test results", and "bug reports")

• Support structured information, i.e. subsections and not just top-level sections.

Even simply editing isn't a nice as it ought to be. Business people might prefer use an MS Word UI for editing: but MS Word produces documents, i.e. "information silos"; but if you don't use MS Word, then you're using what? A WYSIWYG in-browser editor? Or markdown syntax?

Answer 4

A more off-the-wall idea is to look into FitNesse. It is a wiki, primarily aimed at describing business rules (or acceptance requirements) as tests.

Answer 5

I like using the Wiki feature built into FogBugz for this, assuming you already use it for feature/bug tracking. It's handy to have that info in the same tool.

Answer 6

We have used JIRA on a previous project to store around 750 different business rules. JIRA is mostly/kinda-of a bug tracking tool, but it's so powerful and customisable that you can use it for all sorts of workflow/process/knowledge base situations. (BTW - I don't work for the company that produces it).

• Easily updateable: yes
• Diff view: a full change history is available
• Subscribable: yes, has the idea of "watch-lists"
• Role based: yes, feature rich security model
• Attachments: yes, each rule can have it's own attachments
• Search: yes, full-text search available
• Attachment Restriction: hmm - not sure about this one and exactly what you are trying to do.

Some tips if you do decide to go down this path...

• Make use of JIRA's customizable ID's elsewhere to refer to the rule e.g. MYPRJ-334
• Have clear guidelines on what the whatever states you plan to use mean, Proposed, Approved, Implemented, Verified, Dropped.
• The only definition of a rule is in the description - all comments are just comments
• You can link Rule to use cases, components whatever

It's a great approach and I'd really recommend it.