Posts Tagged “documentation”

Please read the next four sentences before letting the dogs loose on me.

I love wikis. Really. And I am not a SharePoint fan. Really.

Now, I only need four more paragraphs to explain.

First, a wiki is supposed to help us make information maintainable. One way we do this is by centralizing and restricting topics to one per page. In order to review and revise a topic in its entirety, all one needs to do is edit the topic page. All the links into the page automatically send readers to the latest revisions.

Second, a wiki is meant to make information more accessible. Topics can be linked to directly, from both within and outside the wiki. By linking to referenced topics at every opportunity, we allow the reader to enter into the conversation at any level of granularity. The reader can then follow links across topics to gather the necessary background information and focus on his or her particular area of interest.

Third, a wiki is an evolving conversation. Pages are created and revised by numerous authors to reflect the current understanding of and thoughts around a given topic. Many pages never, truly, leave a draft status. The goal is not to collectively polish. The goal is to communicate in a collaborative, efficient and effective manner.

Fourth, a wiki is NOT a forum where: (1) each page is a document instead of a topic, (2) the pages rarely link to one another, and (3) each page carries enough information to be consumed outside of the context of wiki itself.  If your wiki looks like this, then what you’ve constructed is a poor-man’s SharePoint (a wiki anti-practice). And your SharePoint wiki is not likely to thrive, since it has none of the benefits of a wiki (maintainability, accessability, consersational tone) and all of the drawbacks (clunky editing, clunky formatting, clunky or nonexistant permissions). If you want a navigatable hierarchy of polished, stand alone pages that do not converse with one another then you’d be better off using SharePoint and Microsoft Word (or open-source alternatives).

Comments No Comments »

The solution sheets practice can be used to quickly and accurately define a previously undocumented feature, user story or initiative. One solution sheet can generate all the detail and agreement required to begin development on a surprisingly large chunk of work. I’ve used this technique to quick start projects, to bid on big fixed cost initiatives, and to provide a sensible alternative to otherwise onerous documentation requirements. Slap a set of solution sheets together to create a ream of USEFUL documentation. Read the rest of this entry »

Comments No Comments »

You can get stuff done faster and be more green by reducing the amount of documentation your team produces. Who would have thought that agile and environmentalism can coincide? Of course, sometimes we do need to document, because it will save us trouble, pain and money down the road. But how does an individual or team decide when to invest in documentation? Here’s a handy checklist of questions to determine whether that document really is worth creating. The answers (or lack thereof) to these questions will shape more valuable documents and keep you from generating unnecessary ones. Read the rest of this entry »

Comments 1 Comment »

Sometimes agile teams have to draft and deliver scope, discovery, requirements or high-level design documentation. I don’t want to get into the how or why in this blog entry. Rather, I want to spend the entry discussing how these documents can be shaped as features and broken into discrete, estimated tasks so they can be prioritized, managed and tracked like any other development work in an agile process. Read the rest of this entry »

Comments No Comments »