Create team activities that will lead to an improved documentation process

Question

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.

Answer 1

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.

Answer 2

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.

Answer 3

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.

Answer 4

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.