Documentation - Get Rid of It!

DZone 's Guide to

Documentation - Get Rid of It!

Documentation is an important part of work for most people working in office spaces. Hundreds of documents are created for this purpose, but what is it for?

· Agile Zone ·
Free Resource

Documentation is an important part of work for most people working in office spaces. It is especially visible in the IT field where an enormous amount of it is produced. Hundreds or thousands of documents are created from the projects initial draft up to finalization. A massive amount of time is spent on writing and then maintaining a never ending stream of documents. What is it all for?

The general purpose of documentation is to structure and preserve knowledge. In software related matters, it can be divided into a few categories:

  • requirements – what has been agreed with a client to implement. What the system will be able to do, what attributes, capabilities, characteristics and quality it should have,
  • architecture/design – overview of the system. How it will be implemented, what parts will it consist of, how it would be integrated, overall design etc.
  • technical – low level documentation. How the particular elements of the system works, what algorithms have been used, possible class diagrams, etc.
  • end user – how to use the system. Possible training materials, tutorials, guidelines.
  • marketing – promotional materials, business cases, etc.

All of the above seem like a requirement for a “standard” project. By a standard project I mean that there is someone who defines the product/system to produce and that there will be receivers/users/customers who will use it.

It appears that documentation is a hard topic for most of companies. Here are some of the most common problems with it, that sooner or later are faced by any organization:

  • inaccurate content, containing vague definitions,
  • outdated data,
  • incorrect data, especially in complex systems,
  • peoples natural unwillingness to create and update documentation,
  • in case of complex documentation, inconsistencies between different documents.

There are many systems, tools and methodologies that can be used to facilitate documentation circulation and maintenance. However, the one I prefer is: get rid of as much as possible.

How is this possible? Requirements and marketing related documents are a must for sure. Only a few kind of projects do not need them. However, this does not apply to technical documents. Whilst it is very important to have general guidelines and a possible overall view on the system, well designed and well written software will be self descriptive. It is quite the same as comments in the code. Well written code does not need comments, it is self descriptive. Putting emphasis from the projects very beginning on simplicity and self-explanation should result in no need for detailed technical documentation. Every new person in the project would be able to scan its structure and from that know the overall concept. Next, digging into any area should result in the same. It would be much faster to get through code, resources and structure than to read documentation (which is probably incorrect).

The same principle applies to tutorials and user trainings. Well designed user interfaces (with possible context dependent help) will eliminate the requirement for complex documentation in this area. Users should be able to easily learn how to use the system just from using it. We see this trend is especially strong in mobile applications and startup projects. As users do not want to spend time learning it, the UI must be user friendly. Maintaining focus on this aspect during project execution would help to decrease the amount of user training and tutorial documentation.

Whenever a new software solution is designed, one of the major concerns should be simplicity and self description. These traits will not only help to spend less time on documentation but will also contribute highly to the project success.

Are you reading docs

Picture by Matt Ray, on Creative Commons

But what if you have to create and maintain documentation? For several reasons it might be your teams inner or outer requirement. One of core principles which I encourage you to apply is to spread work on it through the whole team. Ensure that people will simultaneously work on the task and create or update documentation. With every step of their work, documentation should follow. I do not mean every 5 minutes, depending on the task it might be every hour or every day. However, they shouldn’t wait until the whole job is done to take care of documents. The second principle is to make the documentation change process as light as possible. If you need to review documentation, do not do it upfront. Let people freely change it and do it afterwards. It will be especially easy if they do it in small chunks (and will help a lot with procrastination). Many documentation systems allow you to watch specific documents and get notifications on any change. You can then use it simply to improve or reject changes if needed.

There are teams that are heavily dependant on written guidelines and procedures. It is not a rare case that they are far from the reality. To avoid that, I encourage you to apply the same principle as above. Let people using specific guidelines/procedures freely change and adjust them. They are the ones who know exactly what they are doing, and often also have the best ideas on how to improve. Watch any changes as mentioned above, and improve or reject ones that are incorrect or not acceptable.

In summary, whenever you are able to apply a solution that is simple, obvious and self descriptive – do not hesitate. Search for it! It will allow you to take documentation to the minimum level. And if you have to have documentation, make the change procedures as light as possible and encourage all people involved to use it. If the barrier level for the change will be low and the people committed, documentation will be of a high quality and up to date.

agile, documentation, kanban, lean development

Published at DZone with permission of Piotr Oktaba . See the original article here.

Opinions expressed by DZone contributors are their own.

{{ parent.title || parent.header.title}}

{{ parent.tldr }}

{{ parent.urlSource.name }}