One of my goals for this year is to try to improve the documentation process within the R&D-department. My first step have been to sit down with each developer and talk about documentation in general and how they feel about our current documentation process.

The (almost) unanimous response I got was;

  1. I can't find the documentation I'm looking for.
  2. I don't trust the documentation I find as it is probably outdated because nobody updates documents once they are created.
  3. Process? Well we put whatever document we create in the documents folder and that folder is a mess...
  4. I miss information related to requirements, design and implementation.
  5. Creating documents can be hard. Document templates would help.
  6. It is very important that we document what we should do and what we have done!

This is terrible! Because this means that whatever documentation that is created is "worthless". The good thing is that I there is a common urge from the team to actually fix this.

We have a team building activity coming up in two weeks and my manager have given me a few hours for discussions around this topic. The question is - how would you spend these hours to make sure that you got the best result?

The background to this is that I a while back asked a question on how to resolve the problem of a non-existent pseudo process, How do I improve the development process when the only 'spec' is a "slogan" from management.

As a consequence I have started working more on involving the team around the problems that I see. And less of my just keep presenting solutions to problems they haven't really thought about.

  • 3
    I question your assertion "This is terrible!" - on the contrarary, I think your results are fantastic. There is a strong consensus that you've identified the problem and all parties seem willing to work towards the resolution. That is 2/3 of the problem. Consensus is hard; solutions are easy.
    – MCW
    Jun 10, 2013 at 12:00
  • I agree that I am lucky to have such a strong consensus from the team! But I still think it is really terrible that most the effort going into creating documentation up until now have been in vain...
    – Patrik B
    Jun 10, 2013 at 12:14
  • <b>sunk costs</b> The only thing that matters is whether you have the resources in hand to deliver a solution.
    – MCW
    Jun 10, 2013 at 12:56

4 Answers 4


Sounds to me like there are three clusters of opportunity.

  1. Document templates - How to write a document that supports others using the document.
  2. Document search/storage - How to store a document in a way that supports others finding the information rather than re-creating it.
  3. Documentation procedures - What do we record?

I'd suggest that #3 is not where you want to invest. I'd follow CodeGnome's law to come with a solution to #2 (Decide how you want people to search for documentation - what are they looking for, where are they likely to look, etc. Then design some technology to support that process). I'd come to the meeting with a proposal for that and spend a few minutes vetting the proposal. That could range from a search appliance to some kind of a website.

Then I'd shift to document templates. Once I know where to find the documentation, I want to make it as easy as possible to draft documentation to fill real needs. The document template is going to have to support search, retrieval and trust. That means documents probably won't be structured as old style reams of paper, but should include things like "When was this last reviewed?" and "If I don't understand this, who should I contact?" I'd probably come up with an draft/trial baloon outline for one or two types of documents.

Depending on your corporate culture, the size/cohesion of your team(s) and the intangibles of the team build, I'd brief the suggestions, then break into small groups and design a couple of document templates, brief them to the group. Then I'd try to get people to promise to develop specific documents based on those templates.

  • Interesting, my personal list looks very much alike except for a different priority and the exact words used. I would for instance say that "What do we record" is related to the templates as the templates will contain place holders for different types of information depending on the document types. Instead I would say that the "Documentation procedures" is more related to "How do document types relate to each other" and "How do we ensure that documents contain updated information?".
    – Patrik B
    Jun 10, 2013 at 13:26

I have got an awful suggestion on spending your team-building time.

Actually make each team member write docs

That's it, no powerpoint presentations, no reports, no dancing around the fire, no beating around the bush.

Oh, and leave some time to check what they have done

By allowing most of the team slack off in their chairs while you do the "team building" you simply waste time. The mountain of technical debt is unlikely to get smaller by incantations, there's only one thing that can make it shrink - actual work. Your sessions with the devs showed that everybody was eager to put blame on others - this is a dangerous pattern and should be avoided.

  • The problem I'm facing is that the team wants to write documentation. The problem is that they can't find whats already been written and the documents they produce are all different. This goal of this exercise is to find a common "platform" to build our documentation upon. In the second phase - when we are to implement this - I think that a group activity where we write documentation will be useful.
    – Patrik B
    Jun 17, 2013 at 8:07
  • 1
    @PatrikB - selecting the platform by committee is not likely to yield results if there's no consensus now. It's much better to enforce a dictatorial solution, and then write the docs during the event. Jun 17, 2013 at 9:02
  • You are so right. I will not let a committee define the structure, but I will let the committee discuss my (detailed) proposal. Hopefully we will all agree on the benefits with the proposal. (And with a little bit of luck I will also get some good input on what chapters should go into each template)
    – Patrik B
    Jun 17, 2013 at 10:28
  • Oh, and I do want the teams input. They want to do this so I trust that their suggestions and objections will be beneficial to our documentation routines. My strong belief is that if I can involve the team in the discussions around the new process the implementation of the new process will go smoother.
    – Patrik B
    Jun 17, 2013 at 10:35

One Way to Use Team-Building Time

[H]ow would you spend these hours to make sure that you got the best [documentation process] result?

I would not use a limited time window like that to come up with solutions. You should be iteratively improving process using mechanisms like Sprint Retrospectives (or your framework's equivalent) for that instead.

What I would do is this:

  1. Document your documentation process. Whatever your team says it does, effective or not, document it.
  2. Develop a new process. Whatever your team says will solve the identified problems identified, and that they are on-board with implementing, make sure that's documented in an accessible way.
  3. Use your team-building time to practice the new process. Come up with some small practice samples, and work with your team during that set-aside time to familiarize them with the new process, give them a chance to practice it as a team on something that isn't business critical, and iron out (or at least capture) any emergent issues with the new process.

Some Implementation Suggestions

The Agile Manifesto recommends "[w]orking software over comprehensive documentation," but that doesn't mean documentation isn't important. Assuming yours is an IT project, and without knowing the specifics of it, I'd offer the following suggestions if your team doesn't have any solutions of its own.

  1. Refactor for clarity. Clear code and intuitive user interfaces require less documentation.
  2. Leverage TDD/BDD for documentation. Great unit or integration tests act as functional documentation for a project.
  3. Use documentation-generating tools like RDoc. Generate documentation directly from source code and comments.
  4. Agree on, and implement, coding and commenting standards. Another way to reduce the need to treat documentation as a secondary activity.
  5. Make documentation part of your "definition of done." If it's not done until it's documented, it will be baked into your process.

Obviously, if your R&D isn't software, some of these suggestions may not directly apply to you. However, the overall goals of automating as much of the documentation process as possible and making documentation a first-class, pervasive activity instead of an afterthought will make everyone's life easier.

A self-documenting project is ideal. Even when that's not possible, adding a technical writer to a cross-functional team and making documentation an explicit part of the team's process should go a long way towards improving matters.

  • 60% hardware with low-level programming with multiple types of communication buses, the oldest stuff is 15 years old. 40% is software on Windows platform. So will definitely for something more "strict" than self-documenting code.
    – Patrik B
    Jun 11, 2013 at 19:47
  • Regarding your implementation suggestions - I have already promoted the book "Clean Code" within the apartment and it presents the idea of self-document code in a good way. I will take this with me when I let the team discuss the question "What type of information shall we document?".
    – Patrik B
    Jun 17, 2013 at 8:47

I like CodeGnome's response. I would add

  • Perform peer reviews of your documentation.
  • Come up with a way to organize your documents, even if you have a search engine that works.
  • Establish a file and title naming conventions for your documents.
  • Ensure that every document is under version control. It could be as simple as ensuring there is a table of changes in each document.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Not the answer you're looking for? Browse other questions tagged or ask your own question.