Agile Teams often hold the belief that we should not write anything down because that’s waste. From a human perspective though we need to write things down because that’s the mechanism that allows us, or maybe even forces us, to think things through.

Even the Romans knew that “verba volant, scripta manent,” meaning “the spoken words fly away, written words remain.” So maybe the real question is not “Should we write anything down?” but rather “How much should we write down?” The face-to-face interaction should be followed up with the creation of an artifact that captures what the conversation clarified. This will serve as the basis for further decisions or conversations, or maybe assists in the reexamination of this decision when more data becomes available. Interspersing face-to-face conversations with written thoughts firms up ideas and speeds up the road to shared understanding and clarity.

Usually at this point somebody will jump in to say that all that writing is taking time and that writing a 100-page requirement or design document is a waste. Yes, 100 pages might be a waste most of the time. I think that the artifact produced should be a piece of focused and processed information. If it is 100 pages then it should be indeed a very complex issue, or somebody hasn’t done enough thinking about this. But I’ll leave this topic for another day.

This belief in writing things down was confirmed a few weeks ago as I talked to a new co-worker, Steve Feldman, who writes the Seven Seconds blog. He mentioned that he routinely asks his dev teams to blog about their work. The part of the work that is general in nature can be blogged on their outside blogs, while the company and product specific work should be blogged on the inside blogs. The act of writing things down externalizes the person’s thinking and opens up the ideas for a conversation with the rest of the team.

The blog entry with one’s thoughts will generate further conversation, both online and face-to-face. Each conversation should bring the team closer to identifying and solving the problem that they have set out solve.

Groups large and small use Wikis to capture and share knowledge. As you read page after page of a Wiki, you notice that some pages are good, but others not so much. What traits distinguish a good Wiki page from its mediocre cousins? Here are the four key factors that make a Wiki page good.

A good Wiki page:

1. Focuses on one idea,
2. Provides context for all outgoing links and attachments,
3. Uses attachments wisely, and is
4. Short (500 to 1,000 words).

1. Focus the page on one idea only. Help your reader quickly realize that they are looking at the right page by focusing the page on a well identified topic, subject, or idea. For all the ideas that lay outside of its focus use references to other pages. This will help provide additional material to your readers and will clearly delineate the boundaries of your page.

2. Provide context in the body of the page for all outgoing links and attachments. Weave your content together into a coherent whole with links in context. See my previous post on why a good Wiki tells a story. You need to weave your pages together by providing a context for each outgoing link. The context doesn’t have to be much: a half sentence describing where your link is going, a short paragraph describing the attachment, or a heading for a list of links.

While it easy to quickly create additional pages (sometimes also known as child-pages, or sub-pages) without the link in context, they are not very helpful, and often are difficult to find. Your readers need to know in what order to look at the other pages, or why should they look at those pages. You must provide the necessary guidance by explaining the reasons for any link, and creating a context for them as well. The context will aid searching, and more-importantly, finding, your pages, too.

3. Use attachments wisely, that is: sparingly. When you have a plain text, or rich text document, you need to import that document as a Wiki page. Do not turn the document into an attachment. Just one extra step between your readers and the knowledge they seek may stop them from looking.

Most Wikis still have trouble indexing attachments. Some attachments, notably pictures, drawings don’t lend themselves to easy indexing, therefore if you want to find an attachment, you’ll have to find it based on the context of the page that it is attached to.

4. Keep the page short (500 to 1,000 words). Your readers access the Wiki pages on the screen. Make it easy on them. Short pages help the reader see the entire page at once, or bookmark just the right information for later reference.

Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away.

Antoine de Saint-Exupery

Here are some good Wiki pages from Wikipedia:

1. Atomic Commit: Concise, to the point, with links in context and focused.
2. Two-Phase Commit Protocol: Not short, however kept focused on the topic, with links in context for further information. If the subject demands, you can go longer, just keep in mind that you might loose your reader…

Help your team by writing outstanding Wiki pages! Your team will thank you for them.

You heard of Wikis. You might be using them daily. They are everywhere you look. Unfortunately, quite a few of them are not as useful as they could be. Over the years many of them became dumping grounds for page after page. Now it is almost impossible to figure out what those mean or how they are related. Other Wikis languish for lack of participation. How can you make your Wiki work better for your group of collaborators? Make the Wiki tell a story!

How to turn your Wiki into an engaging story? Follow the advice from story tellers:

1. Decide on the story you want to tell,
2. Create a story line that engages your audience,
3. Tie your pages together into a coherent whole.

1. Decide on the story. What’s the purpose of your Wiki? Is it for a project? Or just to keep track of your ideas? Or to support a product? Whatever it might be, decide on a story that you’d like to tell and build a plot for it. The plot should include the main story line and will include multiple secondary plots. Once you have the plot, write the summary of the story on your starting page in the Wiki.

2. Create a story line. All good Wikis tell a story. Be it the story of a project or of something else. They draw you in and make you click on page after page because they have the information that you want. And where the information is missing a good Wiki compels you to add the missing paragraphs and pages to make the story complete.

3. Tie your pages together into a coherent whole. Decide on a starting point for your Wiki. This is pretty easy since all Wikis have a Home or Main page that serves as the start. As you are writing the “plot” of the story, lay it out across multiple pages, but always make sure that you link one page to another. Before linking to a lengthy “sub-story” in your Wiki, include a summary of that story, and let the user decide if they would want to follow on that link, or just skip to the next chapter.

Practice, practice, practice! Just like with anything else, you’ll get better at writing if you practice. The book Writing the Natural Way by Gabrielle Rico, Ph.D. can help.