Should documentation be a company policy or every programmer's responsibility?

Question

I have been struggling lately with the whole subject of documentation at my current position. I am at a point in my programming career in which I feel I have just been birthed into the whole world of proper and effective documentation. Currently there is very little to be found in any database or source code at the company. User spec documents are generally developed in email threads, on a good day.

I wonder, am I to blame for having not been strict with myself on this issue? Is it the responsibility of the programmer to maintain this and update where needed or found lacking? I have come to the realization that the best way to approach documenting is to pretend that you have one foot out the door, and another soul will have to take over your work.

Thoughts?

Answer 1

I understand your pain when it comes to the lack of documentation.   I constantly find myself on projects without clearly defined requirements because the requirements document exists in someone's head somewhere stemming from a conversation that took place four years ago.

I feel it depends to some degree on the project, the documentation, and your position, amongst other factors.   If you're at the bottom of your food chain, I'd say there are limitations to how much you can enforce proper documentation, other than documenting your own code as much as you're alloted time to.   The folks I work for.. well, they're generally pretty code-as-we-go, so when I put time aside to do design spec documents and such like, I tend to get "oh.. right yeah.. that's important.. right" and can't get it to stick with the rest of the crew.  

The best summation of an answer I can provide is the responsibility lies in both parties to some degree. Yes, the company should have policies dictating documentation, but in lieu thereof, don't be afraid to step up and do what you can yourself so when a four year project lands in someone else's lap they've got something to work with.

Answer 2

Documentantion standards should be policed by the company. If no such policy exists yet, management should gather with the developers and agree on a reasonable set of documentation that is obligatory for each and every project.

Answer 3

It should be company policy, absolutely.

Here's why (as you alluded to): turnover.

For a competent software team to run smoothly, it should always assume that any single developer might get hit by a truck at any time. Documentation should be done in such a way that any decent programmer can be dropped into the unfortunate dead developer's role at any moment - with a minimum of hassle and ramp up time.

The tricky bit is that you can't easily measure this. It really depends on the situation and the team. Agile shops might not have much formal documentation, for example, but if they have good processes in place, it won't matter too much. On the flipside, a hardcore Waterfall shop which relies on strong documentation will struggle much more if the documentation is neglected and out of date and some senior developer gets hit by a truck.

At any rate, this should be dictated by the company. After all, if the company is an Agile shop or a Waterfall shop - they will obviously be inducting their new developers into whichever process they have in place - so it's not really up to individual developers to rock the boat (unless, of course, the documentation/process situation is so dismal that you're trying to introduce one in the first place!).

Answer 4

If you are creating something like a platform. then, definitely, it is every programmer's responsiblity to document his/her code. since programmers create it, and code creator understand the code the best.

It is will be a disaster for someone else to document your code.

And,progrommer writing document should also be a company policy.

Answer 5

If I'm understanding your question correctly, the documentation that you're referring too would be akin to providing your customers manuals on how to use your product or other data of a similar nature? If if that type of documentation, I've found it's more the responsibility of the technical writer, or failing that, the lead developer/project manager.

As for code documentation, yes that is the developers responsibility. At the very least it'll save you wondering what your code did if the code isn't touched for a while.