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 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?

share|improve this question
    
Are you in a situation where you are being told that you need to produce documentation, but there is no real history of quality documentation at the company? Or in a situation where you personally believe that you need to produce documentation which is better than the company has done previously? –  Carson63000 Mar 25 '11 at 2:28
    
Good Question. This is a situation where I believe I need to produce better documentation than has been done before. That and the fact that I am leaving the company very soon. –  Spacemoses Mar 25 '11 at 2:33
    
I don't see how this is an either/or issue. It should be company policy that each programmer take responsibility for documentation. –  oosterwal Mar 25 '11 at 14:03
add comment

5 Answers

up vote 4 down vote accepted

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.

share|improve this answer
    
Yeah, this is pretty much right on for describing my situation. I think that I will be learning from the lesson as I move on and "do what I can". –  Spacemoses Mar 25 '11 at 2:46
1  
Unfortunately, a lot of employers and project managers don't see a value in documentation. Contracts are done at either some fixed number of dollars or hours. Every hour of your work takes up money from that pool. It's easy to see hours spent not-coding as hours bleeding from the pool. It can be easy to miss how much documentation can SAVE hours down the road in avoided reworking to meet missed requirements, fix bugs for tests not covered in testing docs, and the like. –  trycatch Mar 25 '11 at 3:09
add comment

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.

share|improve this answer
add comment

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!).

share|improve this answer
1  
I don't like to use the "..gets hit by a truck" angle. Far too easy for management to just think "well, that's never happened before, probably never will either." Instead, focus on how important documentation is when the day comes around that your senior developer quits to accept a better job. Every manager has seen that happen! –  Carson63000 Mar 26 '11 at 6:31
    
@Carson63000: +1. Good point. :) –  Bobby Tables Mar 26 '11 at 10:33
add comment

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.

share|improve this answer
add comment

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.

share|improve this answer
    
Yes, this would be one flavor. I guess I'm looking at anything from source code documenting, to project specs, to end user documentation. Any of this. –  Spacemoses Mar 25 '11 at 2:39
add comment

Your Answer

 
discard

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.