[#ALM] To document or not to document? (I’ll cut your hands!)

Buenas,

We began with an affirmation of those that only fans and view short typically drop with so much pleasure:

“Generate documentation in a project is absolutely useless”

or any of its variants, such as “documentation is a waste of time“, “document is for losers“, “…“, etc. As I am a person of gray, I’m going to add a couple of nuances to this line of thinking.

Image may be NSFW.
Clik here to view.

The problem with the documentation are not their bases, I always go to the most basic level, that would be something like:

“Someone tells us what you need, someone writes it and then build it”

The problem is that for a long time, many people devoted themselves to invest more time in defining how you should write this information, instead of writing which need a person. Processes in which the bureaucracy of them made that the final results would be impossible were created from this point. There was a big distance between the time in which is drafted to do, and when that was delivered the result, usually writing about pears and apples were given. But of course, the problem was not the documentation itself, but the process on which it rested. We are that it was a problem of communication .

Image may be NSFW.
Clik here to view.

Currently, agile schools propose much simpler mechanisms for writing this information and they begin a phase of construction that allows in less time to validate the written. (User Stories, Product Backlogs, etc.)

Then we come back to the point that dictates the title of this post:

How to find the right level of documentation for a project?

The answer is 100% ambiguous:

“Itdepends on each project.”

My recommendation is:

Always starts with a minimum of documentation for a project. For example, only creating user Stories .

Begin an approach less-to-much, i.e. begin with simple User Stories and from there start to supplement it as required. This approach allows us to have a minimum of documentation, and if necessary, automatically generate documents that are required on this minimum. For example, if we use the tools of Visual Studio 2012 modeling, we can automate the process of generation of documentation to generate all kinds of UML artifacts that are usually required. This case also has the advantage of reflecting what they are generating 100% (or almost) product which is our code.

Usually in environments where it is required to comply with high levels of documentation, it is only to complete formalities, but rarely for use as actually defined in the process. Many times I’ve been in situations where the X functionality being discussed or and a product on the documentation of it, and in reality the product generated did not reflect the initial documentation. That is why, that the 2nd Council is as follows:

“Attempts to always automate documentation generation mechanisms so that it is generated from the code“

Techniques such as Behavior Driven Development or Test Driven Development they are excellent drivers to have a model in which the documentation “arise” naturally the code (and the test Image may be NSFW.
Clik here to view.

So now you know, document is not as bad as it seems; the sensitivity is to find the right way of doing so in a project around the world “understand it”.

Latest example: recently I participated in a project where we work with people from several cities in Spain. We were several lines by pulling at the same time, after a couple of months around the world would be handled naturally among the 40 or more projects in the solution (I am speaking of having many technologies mixed in one place). At some point joined the people of USA for the Release Management and I realized that although I had very clear, what incorporábamos in versions 1.0, 1.1, 1.2, etc.; This information was not very clear if you didn’t know how to “read comments” and the structure of our PBIs and tasks in the TFS. So at that moment, raised me 2 options: I was trying to explain to them our day to day packaging of USA team or… created a fileversions.txt .

Obviously opted for the 2nd option. My only additional task of documentation consisted of completing a text file with the most relevant points included in each new branch of the product.This task was an additional step more each time that it created a branch of RELEASE and was the point where the Packaging team identified the elements that were included in each version. I consider this task a task of documentation and not deny it. I see that the results and benefits that gives me are much more valuable than other options.

Note: if not it sounds the concept of releases by branches or you are missing something in context, my book of ALM you can help. Here -

Saludos @ La Finca

El Bruno