Vukoje's blog about software development

How should we organize software documentation?

In my previous blog post I've said something about the reasons of documenting software. Now the question is how to do it? People don't like to write documentation, documentation is often hard to find and maintain and it is usually obsolete. We need to organize documentation in such way that it is meaningful, easy to maintain, easy to find and hard to become obsolete. You can say that right solution is somewhere between full bureaucracy and anarchy.

Process oriented solution

Some people believe that with detailed organization and business processes they can completely controls their business. This approach is something like programming humans that are executed by business process. In this environment programmer would have to follow exact documenting process and typically fill big documentation templates with concrete information. This procedure can guarantee that people will avoid documenting at all costs and it doesn't guarantee that information populated in templates will be useful enough. It may give away false impression of fully controlling this vital activity but in practice it isn't so.

Programmers dislike (hate) writing software documentation because it is not interesting and creative. If they are further more crippled by heavy formal process, programmers will do what ever they can just to finish that part of work by filling templates with low quality and incomplete information.

If it is not easy for programmer to find and update some information he simply won’t do it (if he is not explicitly asked to do it). As software evolves and knowledge of the real system increases, documentation becomes obsolete because programmers are not updating it. After enough time has passed you are faced with massive obsolete documentation that in the end of the day is making more harm than good because you can never know if information is accurate.

People oriented solution

My opinion is that company Wiki site (e.g. ScrewTurn Wiki ) is much better solution for knowledge base than bunch of populated word templates resting on some server's file system. Pages on Wiki site are easier to search, easier to alter and they can automatically notify all participants when documentation changes. This approach can seam frightening to management because everyone can alter any document they want. In general, employees shouldn't be constrained in their work so that they can not make mistake. Not being able to make mistake means that you aren't doing any creative work and that you should be replaced with machine. Instead, company should introduce quality checks for activities that are more likely to introduce an error or where error can be very expensive. Some dedicated person (e.g. project leader) could inspect all documentation incremental changes in previous weak and verify them. Bear in mind that almost all Wikis will automatically store document versions and track changes. This way person who made mistake can always easily be identified and document can easily be rolled back to previous version.

After you created infrastructure for easy and fast document manipulation you still need to create firm climate (culture) to motivate people to contribute to knowledge base. This is the only way that firm knowledge will grow and knowledge will be effectively passed between coworkers. After all, what are knowledge workers without good knowledge base?

In my next post I will write about what should be documented and how, so if you are interested hook up to my blog feed and stay tuned.
What are your experiences with writing software documentation? 

Comments (12) -

  • Veki

    2/17/2009 4:53:39 AM | Reply

    Nice post!
    In the half of my reading I was started to think about using WIKI, and you finnaly mentioned it.

    Good thinks about WIKI *that are not so obvious:
    0* easy update, easy writing,...
    1* You can see which people write the best articles and which are just doing wrong job
    2* Wiki support also templates

    My question: Could you provide us with one example of your documentation. Just to see fields. Problems can occur when some functionalities can not be written in particular template. What you do when you find some exception?

  • vukoje

    2/17/2009 3:14:56 PM | Reply

    @Veki : In my firm (, we are using word templates for use cases and some related documentation, and we use wiki to share other knowledge. Other knowledge is often regarding some technology issues, but it can also be manual for configuring wireless access.
    My strong opinion is that text in free form is enough to capture knowledge.

    I'm thinking about your question regarding exceptions. This situation implies to me that templates introduce more complexity to something that shouldn't be complex. In the end you just want to write something down so other people will know it and you don't have to rely on your memory. Once you have problem, not with expressing what you know but with writing it down, you can be sure that you have taken the wrong path. I remember similar problem with Use Cases that were defined using specialization and referencing, result was documentation to complex to be used by our test team.

    I hope this was helpful. I will cover this theme more in following posts and I hope I will show you example of some Use case template.

  • ildi

    8/27/2010 5:08:21 AM | Reply

    It’s a very nice approach to the problem. I read everything you wrote about documentation in this blog. It’s very useful to me. Thanks for sharing it!

    You may say I’m idealistic, but I would like to show the problem in a different view.

    In my opinion good documentation can be created only with the appropriate approach. And this is the same as in all other branches, where quality is a target (approach already set in 1945, see
    1. quality comes first, not short-term profits
    2. the customer comes first, not the producer.
    In our terms this ideal approach could be translated as:
    1. Set project deadlines in such a way, that documentation tasks can also be performed in a good quality
    2. Reader’s interest of understanding comes first, the writer’s problems come afterwards.

    Writing good documentation means to me that the reader should understand what the writer knows and wants to share with the reader about the software. Good documentation should play the role of a good teacher, who is pleased to catch the shimmer of understanding in his/hers students’ eyes. And – you know – this is a really big challenge. The main difficulty is: how should the writer explain things in such a manner that it could be understood by the reader? (assuming an adequate level of understanding of the reader, of course)

    To add a problem to your problem list: software developers are generally not the kind of people, who like to explain things to other people. Maybe software project teams should have a team member, who is willing to do good documentation and also understands software?

    What do you think about this?

  • vukoje

    8/29/2010 9:31:36 AM | Reply

    Hi Ildi,

    You said this grate:
    "Reader’s interest of understanding comes first, the writer’s problems come afterward."

    I think that each team of developers should have one person, the team leader, responsible for all the development issues. His responsibility should be, among other things, to remind developers to document valuable things and also to coach team to have right approach to writing documentation.

    In our daily meetings, each developer has to state which problems and unknowns he is facing right now. Also when some dev. solves the problem, he informs the team about the solution and someone always asks: "Did you document it?"

    We don't want another person to take time solving that same problem again. Being lazy and relying on memory has proven just plain wrong so many times.

    Note that sometimes small comment in code will be enough.
    Also checkout this grate link

  • ildi

    8/31/2010 6:41:29 AM | Reply

    Hello Vukoje,

    Thanks for the link shown to me, I read a lot of the site and tried to learn from good practice. Of course, we have to keep track of what experience shows in many years of work in IT projects:  TAGRI, They Aren't Gonna Read It, and surely not all of it.

    Still, we have to write documentation, but in a wise and balanced way: short, clear and understandable (for inner purposes and for the customer) as well as cheap and profitable (for the stakeholders).

    It seems to me, that the role of a team member writing documentation of good quality (which I wrote about that - I felt - is somehow missing in IT projects) can be the technical writer, a person who knows a lot in effectiveness of documentation. Having a technical writer doesn’t mean that software developers are absolved from writing documentation, their drafts and good enough descriptions can be turned into documentation a customer needs (see

  • vukoje

    9/8/2010 3:32:58 PM | Reply

    Hi ildi,

    Thanks for the link. Me and my team had discussion some time ago where we concluded that writing good technical documentation is hard and that we suck at it Smile Also I'm not satisfied with our requirements gathering process.
    So, when time permits me I will start with reading "Writing Effective Use Cases" by Alistair Cockburn.

  • ildi

    9/10/2010 2:46:36 AM | Reply

    Hi Vukoje,

    If I understand you quite well, you also don’t have a technical writer in your team. Did you ever think of having a technical writer at your firm? I wondered if this activity (which can be done well certainly only with vocation) can be turned into a job at software firms. What would your manager say?

    And until you don’t have a technical writer, here is a link, which was also very useful for writing short and good documentation:

    When I learn from books written by big software firms, I am always astonished: the books are beautiful and understandable. The look-and-feel(-and smell) of such technical books can make me happy. And I wonder: What it would be like to be able to give our customers this feeling to? How expensive would it be to produce this kind of quality in our firm? Very expensive, for sure. Again, what would your manager say? Can you imagine that producing software documentation in this quality will be economically worth one day?

  • vukoje

    9/12/2010 7:05:26 PM | Reply

    Hi ildi,

    Thanks for the link.
    You are right, we don't have technical writer in out team.
    I guess that some firm could have a dedicated technical writer, but the need for that as full time position depends on size of the firm and type of software being developed by that firm.

    We are small company (about 20 employees) focused on agile software development, so I don't think we need this kind of worker.
    I will tell you how would I like to implement this.
    When I think of technical documentation, I think of help & manuals, use cases & business analysis, and implementation documentation.

    All of these documents are being created by different people (developers, testers, supporters, analyst...) so it is not a option
    to have one person writing all these documents. Also I would never like to have all the knowledge/power concentrated in one person. Instead I would like to have one person in firm dedicated to issues related to writing technical documentation. This person should be best in this issues, giving support and reviewing other people writings. I for example am responsible for maintaining, coaching and inspecting coding standard in my firm.

  • ildi

    10/1/2010 4:18:25 AM | Reply

    Have you thought of writing a post on Software Quality?
    It would be very nice to read good advice on this isue.
    Thank you,

  • Builders software

    1/28/2011 11:27:54 PM | Reply

    Software documentation or source code documentation is written text that accompanies computer software. It either explains how it operates or how to use it, and may mean different things to people in different roles.