

Software documentation as a guidebook - AliCollins
http://www.codingthearchitecture.com/2013/01/15/software_documentation_as_a_guidebook.html

======
vineet
I agree that the problem is that when most people think 'documentation' for
software projects, they think of comprehensive documentation - something that
is not only very hard to do, but also almost always a bad idea.

I also agree with something that is implied in the article - that
documentation should be of multiple types: including wiki and UML, but also
unit and integration tests.

The part that I find interesting, is that the above results in three things:
Be open to the fact that each documentation type might have diminishing
returns, so as developers we should not be religious about just UML or just
unit tests, but be make sure to have multiple types of documentation. Realize
the obvious that that documentation should not get in the way from the project
responding to customer needs (i.e. code base being agile), and therefore the
documentation must be ideally as less as possible. And that finally, there
needs to be a way to find the right type of documentation when you want it.

I think the last part is a field where there needs to be research. Getting it
correct has been one reason why unit tests have worked so effectively. We need
more people thinking about this part.

------
AliCollins
Does anyone think of Documentation as a feature? When documentation - which is
typically not the most fun bit of a project - has to be fought for by the
developers, to have any more than the most basic hand-wavy guide to what's
going on can seem an unnecessary luxury...or so management may think!

But then do I make it a point to make sure my code IS well documented? Maybe
another resolution for this year..!

~~~
vineet
If your opinion do you see management not wanting documentation? I have
generally seen the exact opposite to happen (the managers want documentation,
the developers think it is a waste of time).

But, to your point, I would not consider documentation a feature, just like I
would not consider making a commit a feature, or talking to other developers
as a feature. I think that some form of documentation is necessary (or you
will regret it).

The hard question (in my opinion) is what should the documentation contain...
I believe that answer involves getting the opinion of a coworker, to get a
sense of what is-not/can-not be well explained in the code.

