How should I choose the right documentation for my team?

Question

I've asked this question a few days ago about how much documentation should be made and now I realize I may have been asking only half of the question.

My goal is to promote some sort of documentation in order to increase continuous knowledge inside the team.

My team is working mainly on server-side services which extends proprietary devices which are distributed locally (national not global)

In addition we supply APIs and administration web apps to those services.

What would be the best types of documentation for my team?

Should we focus on DFDs, sequence diagrams, class diagrams, just plain text... ?

Are some documentation methodologies better for specific industries or are there some which are just a waste of time?

I fear this last question would be put down as too subjective, but I do hope there are some standard answers for this question, similarly to when someone asks about good OOP techniques and gets directed to design patterns and SOLID principles.

Answer 1

In Agile Software Development, Uncle Bob once wrote his First Law of Documentation "Produce no document unless it's need is immediate and significant." As has been typical of such comments in the Agile world, this has been misquoted and misinterpreted many times. So he later went on to clarify.

Agile Methods require two kinds of documentation: Requirements and Design Documents. All other kinds of documents are optional within Agile Methods; but optional does not mean absent.

Requirements. In Agile Methods, the requirements are documented one iteration at a time. Requirements are often identified long in advance of their development, but they are not fleshed out until the iteration in which they are developed begins. Moreover, they are written as automated acceptance tests. Other kinds of requirements documentation, such a narratives, workflows, and storyboards may also optionally be created.

Design Documents. In Agile Methods the design is documented by creating unit tests using Test Driven Development. These unit tests are working examples of how to use each part of the code. Other kinds of design documents, such as class diagrams, interaction diagrams, state charts, ER diagrams, etc. may optionally be created too.

Note the last paragraph in particular. It is sometimes ridiculous for developers to write documentation for other developers in English. Never forget that there is another common language that developers speak: code. Unlike English, code is self-validating.

Using unit tests to document the intent of the application code is a brilliant way of writing documentation. Why? Because they're guaranteed to remain up-to-date.

Further, and perhaps more relevant to your situation, he writes:

Documents that the development team decides they need, are simply created as and when they are needed. Documents that the business decides they need, and that the development team does not need for their own purposes, are written as story cards, and estimated, planned and scheduled as all story cards are. If they never get selected for an iteration, then they must not have been all that valuable to the business. If, however, they get scheduled for an iteration, the business must have considered them important enough to schedule.

This is a technique I use all the time for figuring out what is genuinely useful documentation. If the development team feels they need it, just give them the means (a wiki) and they will write it, without being asked. If the business feels they need it, queue it up as a job next to everything else, and see if they decide they need it more than they need other work.

Answer 2

You should concentrate on what that your team will actually read. There is no point at all to focus on anything, if you haven't got the slightest idea of how your team will respond.

Your best bet is to make documentation part of the process and include everyone in it. There should be some consistency, but let's worry about that when there's actual documentation. What we've done is pretty simple: we added a documentation and a code review sub task to every issue. No issue is resolved, until all sub tasks are resolved, so everyone has to write their own documentation and review others' code.

We use a wiki, so documentation is ever evolving, and at first everyone went about it their own way. For example, I was the only one that used DFDs. After a few months, we started copying each other's style, learning from each other, and we reached a point of quasi-consistent documentation. I went back and revised older posts, and let's say we are at a point where our documentation is good enough.

It would be best not to let anyone get too creative, but other than that, having a quasi-consistent documentation is better than worrying about best practices and industry standards, and never actually getting to write the damn thing.

To summarize, my generic guidelines for documentation are:

1. Write the damn thing,
2. Be consistent.
3. Worry about everything else afterwards.

Answer 3

Measure, and use your measurements to guide you. You probably can't (and shouldn't) do split testing on the members of a small group of programmers, but you can change the documentation used at different times, or on different components.

Introduce DFDs: do they help? ...oh, wait, what does it mean to "help"? There are a number of quantities you could measure: team velocity, defect density, team satisfaction, and probably others. So choose the measurements that are important to your team's performance, and find out how different documentation processes/artefacts affect them.

The point here is that documentation is a communication tool, so answering "what documentation should we use?" is tacitly addressing "how does my team communicate?" I don't know that, but you can find out, and you can tailor your documentation strategy to help the people on your team.

Answer 4

What would be the best types of documentation for my team?

I am not sure if system documentation have standard types. However, system documentation has goals. These goals stem from the methodology used and the system development phase used. System documentation is also affected by standards such as CMM.

Should we focus on DFDs, sequence diagrams, class diagrams, just plain text... ?

Each type of diagram serves a purpose and is usually tied to a methodology. DFDs are part of Structured Analysis and they are commonly used to describe data flows across systems, programs, and to describe overall system (or subsystem) inputs and outputs. Class diagrams are part of the UML and the OOA/OOD world. Class diagrams are used to document classes in a system/subsystem and in many cases as the basis for other diagrams and to generate DDLs. Plain text is important for specifying and describing business rules.

Are some documentation methodologies better for specific industries or are there some which are just a waste of time?

Contrary to some people belief's, documentation is NOT a waste of time if done consistently and correctly.

What you must do is study the value of documentation and put in place the specific documents that will be describe your system and that will add value in each of the system development phases, then educate your team in the techniques and value of this work. Most importantly is to plan for all of this in your project schedule.

Answer 5

Do not provide printed documentation to your team because project requirements and implementation architecture are changing during the project life: Developers don't also read the printed documentation As soon as the code implementation or requirements are changed then the documentation is not anymore accurate.

Having said that I have no silver bullet except to create class diagrams which are synchronized with requirements and code.