Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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.

share|improve this question
similarly to when someone asks about good OOP techniques and gets directed to design patterns and SOLID principles. Similarly? When we are presented with a technical problem, we can point to the better practices & principles. But, we don't know your team, how could we know what would work for you guys? –  Yannis Rizos Feb 5 '12 at 8:12
maybe I'm having troubles explaining myself... I meant that for some questions there are obvious responses. maybe for documentation there are some obvious answers as well? for example: "don't waste your time writing sequence diagrams, they are hard to maintain and hard to understand" or "document class diagrams only when you got a special class-structure" and all sorts of tips and advices that will save my team and the future readers of this question some time when approaching documentation –  Mithir Feb 5 '12 at 8:36
No, your point got across perfectly, I just happen to disagree with it. What may be hard for you to maintain / understand, can be quite easy for me, and vice versa. We can't really extract general tips for such processes. Every popular documentation methodology may work or not for your team, the only way to be certain is to ask your team. Generic guidelines: 1) Write the damn thing, 2) Be consistent. 3) Worry about anything else, afterwards. - btw my comment is only for the last paragraph of your question, that has nothing to do with the core question itself. –  Yannis Rizos Feb 5 '12 at 8:41
"maybe for documentation there are some obvious answers as well?" If there were obvious answers, you'd already have been forced to follow them. As with good programming -- the obvious things (like having the code pass tests) is obvious and everyone forces you to do it. If you aren't forced, there's no "obvious" standard answer. –  S.Lott Feb 5 '12 at 14:09
@S.Lott I disagree. 1st: for example, its obvious that good OOP follows design patterns and SOLID principles but many programmers don't even know about them (they forgot). 2nd: I know I'm a little ignorant here, thats why I am asking, if I had the notion that "if it was important I would know about it" then I wouldn't learn anything new. 3rd: you'll be amazed how much "cutting corners" is done in some places... maybe you work in a place in which everything works according to standards and all is perfect, but some of us don't. –  Mithir Feb 6 '12 at 6:31
show 3 more comments

5 Answers

up vote 6 down vote accepted

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.

share|improve this answer
+1 for "Produce no document unless it's need is immediate and significant.". In building APIs, I find the tests the best place to go to show literally how each part of an API should be used. The difficulty is sometimes knowing when to start, which is where a very broad concept document or diagram is probably the minimum documentation I've found is needed to reduce the learning curve. Having a good project/issue tracker with a built-in wiki also helps to document the code in a more abstract form, allowing expansion when the team decides it's needed. –  S.Robins Feb 5 '12 at 11:50
add comment

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.
share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
add comment

Your Answer


By posting your answer, you agree to the privacy policy and terms of service.

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