Comments on: Design Documentation http://pathfindersoftware.com/2009/07/just-enough-documentation/ The Fastest Way to Launch Successful Software Thu, 19 Jan 2012 16:36:03 +0000 hourly 1 http://wordpress.org/?v=3.3.1 By: Alice Toth http://pathfindersoftware.com/2009/07/just-enough-documentation/#comment-9706 Alice Toth Thu, 13 Aug 2009 16:51:46 +0000 http://www.pathf.com/blogs/?p=3358#comment-9706 Organizing a wiki can indeed be tricky and I try to minimize interlinking on requirements because it's too easy to lose your train of thought. At Pathfinder, I came up with a requirements template that is contained to one wiki page. We can do this in part because we do agile design and development which means we only write requirements for the features that are to be built in the next iteration. Since we have two-week iterations, features are never these epic stories and the requirements can reside on one page. The biggest advantage I've seen is that it's easy for all team members to scroll down to the area that interests them most and then easily scroll to a reference in another section (e.g., design specs referencing a wireframe). When going through various iterations of the requirements template, their feedback was that scrolling a long page isn't a bother but clicking to a new page is. So, one page it is. Organizing a wiki can indeed be tricky and I try to minimize interlinking on requirements because it’s too easy to lose your train of thought.

At Pathfinder, I came up with a requirements template that is contained to one wiki page. We can do this in part because we do agile design and development which means we only write requirements for the features that are to be built in the next iteration. Since we have two-week iterations, features are never these epic stories and the requirements can reside on one page.

The biggest advantage I’ve seen is that it’s easy for all team members to scroll down to the area that interests them most and then easily scroll to a reference in another section (e.g., design specs referencing a wireframe). When going through various iterations of the requirements template, their feedback was that scrolling a long page isn’t a bother but clicking to a new page is. So, one page it is.

]]> By: Steve R http://pathfindersoftware.com/2009/07/just-enough-documentation/#comment-9705 Steve R Thu, 13 Aug 2009 15:10:34 +0000 http://www.pathf.com/blogs/?p=3358#comment-9705 Good advice, Alice! We've been using wikis for documenting requirements for three years now and have found that it works wonderfully for collaboration among the design and dev team, but is still difficult for business contributors to know "where they are" in terms of validating the requirements. Since our wiki requirements are highly interlinked, it's a challenge for validators to follow links, reading requirements, and knowing when they are "done." They tend to prefer linear, document-based requirements documents. Have you found a good balance between these different needs? Good advice, Alice! We’ve been using wikis for documenting requirements for three years now and have found that it works wonderfully for collaboration among the design and dev team, but is still difficult for business contributors to know “where they are” in terms of validating the requirements.

Since our wiki requirements are highly interlinked, it’s a challenge for validators to follow links, reading requirements, and knowing when they are “done.” They tend to prefer linear, document-based requirements documents.

Have you found a good balance between these different needs?

]]>