|
Hiring Q: Value of documentation?
I was idly surfing monster and I saw a posting for a programmer position. They asked applicants to answer three questions as part of their application. The first question was:
"What is the value of documentation?"
What do you think is the value of this question for deciding who gets an interview?
http://www.braithwaite-lee.com/opinions/documentation.html
Reginald Braithwaite-Lee
Thursday, October 9, 2003
To me, there are two types of documentation: functional and compliance.
Functional documentation is that which is necessary in order to complete the task at hand. It has value only if it is accurate and therefore should be as small as possible. UML diagrams on a napkin are okay. 1-2 page architecure overviews are great. 1000 page design documents are evil. The leaner the documentation, the more valuable it is in the long term.
Compliance documentation is that which is used, usually by managers, to ensure you are doing what you're supposed to be doing. It may (or may not) be necessary, but has no value. Put as little effort as necessary into it.
Just my $0.02
anon
Thursday, October 9, 2003
I think the only value in interviewing is sorting out damaged goods and the completely unprofessional and clueless types.
IE: the candidates who look at you like you have a horn growing out of your head when you utter "documentation"; and the candidates who scoff, ridicule, and/or get defensive about their absolute, religiously based refusal to cooperate with documentation standards. I'd rather not be in the same department, team, etc with these types unless their work has absolutely no intersection with mine. They suck.
Also, I think anon hit the nail on the head from a different perspective. Everyone with management and "doing things right" allegiances will swear that they are into proper documentation, but the reality is generally that it requires human continuity to pass technical design knowledge along. Usually, the next guy won't and can't understand what was written by the absent/dead/fired/outsourced former developer.
Bored Bystander
Thursday, October 9, 2003
So, anon, what do you think about asking this question as part of the hiring process? Good idea? Bad idea?
I wonder whether:
- they have a particular point of view and want to filter for people "on the same page"
- they are looking for people who can express themselves well and this question is as good as any
-they are looking for a particular attitude, perhaps someone who is diplomatic and can discuss pros and cons without antagonising anyone
???
Reginald Braithwaite-Lee
Thursday, October 9, 2003
You've really killed the thread with the last question. All of the above. But the question of "value of documentation" is interesting. I too fear the programmer/developer and EVEN manager who fear documentation. I was at a place where the manage would praise those who did "work" without documentation. Yes, it was a complete joke. On the other hand, we had to work with the Core IT group and they used documentation to HIDE from work. The IT people seemed to have learned the facade of IT but really didn't know how to do anything and they would postpone and need to meet and study things that did not need documentation, other than what a programmer would put in his code. Without a doubt, good documentation is good, bad documenation is bad. What makes the difference between good and bad ... that is the question and the answer is, it depends.
Me
Thursday, October 9, 2003
A couple of data points:
1. I can think of at least two open-source software packages that I have given up on due to the quality of their documentation (ANTLR 2 and Courier MTA).
2. If you work as an outsource service supplier then design documentation including specifications and ECOs is critical to the management of fixed-price contracts.
David Jones
Thursday, October 9, 2003
I've known quite a few Delphi/VB programmers that wholly attribute Delphi's failure to the quality of Borland's documentation (Microsoft's was as good as Delphi's was bad)
Philo
Philo
Thursday, October 9, 2003
That's strange, when I was using Delphi I thought its documentation was far superior to Microsoft's.
Sure, there's not as much of it, but that's its big advantage - I could actually find what I was looking for in the Delphi help. In MSDN, it's impossible to find anything unless you already know what you're looking for, there's so much crap in there.
Sum Dum Gai
Thursday, October 9, 2003
Do you still have the page you found it on?
It sounds like a bad question if you're looking for people straight from CS academia, because they don't have the constraints of business teaching them that certain kinds of documentation are infeasible. They'll probably all be writing essays on why documentation is like string cheese. (The more, the merrier.)
However, for experienced industry people, it sounds pretty awesome. You can filter out those who just don't want to communicate, and from the rest you get a spectrum of opinions. Though, one problem is that there's only one book I know that tries to define what good documentation is (that MS Press book everyone here likes...). But it sounds worthwhile to try asking anyway. I wish everyone tried asking thoughtful questions as a condition for working together. If only people applied this to their own marriages and parenting...
Tayssir John Gabbour
Friday, October 10, 2003
Interviewee: Oh yeah man, documentation is really, like you know, important.
Interviewer: Can you remember an occasion when using documentation helped you or perhaps didn't help you?
Interviewee: Uh well, there was this time, long time ago, you know when I started? Well this one time I'd spent days on trying to fix this problem man, you know? Anyhow, I tried everything, man, just everything. Deebuggers, print statements, I even spell checked the whole source man. And you know what?
Interviewer: No, what?
Interviewee: I found the answer in the documentation man! It was there all the time! Like wow!
Interviewer: So, now you start with the documentation?
Interviewee: Umm, well there was just this one time you know? Mostly I gets it right off. I'm really good at nailing those small lil' bugs you know.
Interviewer: Thankyou, we'll be in touch.
Simon Lucy
Friday, October 10, 2003
If documentation is done right, it will save time downstream for you and others.
For example, writing comments and PDL before writing the code itself can make you an order of magnitude more efficient. By commenting first, you force yourself to clarify your purposes and think through what you're going to write. Whenever I've written projects in this way I've found that the coding itself goes like greased lightning. The debugging is about fixing minor errors; rarely do I find that something is so radically wrong that it needs to be redesigned from scratch. It may or may not save on total coding time, but by golly does the code turn out robust.
And well-written specs and user guides really do help others who have to work on, or use, your app. It should be possible to lay out a spec so that anyone can see where to find the answer to their question.
The trouble is that people are so used to poor documentation that it's the last place they look.
Of course, you also have people who can't be bothered reading and would rather be spoonfed, but there's not much you can do about that ;-)
A case in point would be a mission-critical task that was passed on to me by my predecessor. It turned out that there was no application to perform this task; rather, there was a heap of scatterware and a "user guide" consisting of twenty steps, most of them to be done manually.
It turned out that even that was not sufficient. Much of the scatterware was unavailable, didn't run correctly, or didn't run at all. Crucial information had been omitted. I spent three days trying to get the task completed - that's three actual days of 24 hours, not three working days. (OK, I exaggerate. I only worked three 20-hour days. But that was unpleasant enough.)
The first thing I did was document the steps I actually had to take to carry out the task. Without this, I would have had no basis for any design and no way to repeat the task the next time it needed to be done.
Now the task is well on its way to automation. In the meantime, we at least have a reliable, repeatable manual process, so the team isn't dependent on knowledge that exists only in my head.
Even after the automation is complete, a full description of the process will be crucial to maintaining the application and making sure it's providing accurate data.
Not that that helps. I need someone to deputize for me because I have to be away the next time the task is due. It's no good telling other team members that I've documented the process in such a way that anyone with minimal knowledge of programming can carry it out. They say that, whatever I've written, it cannot possibly be any use to anyone without prior knowledge of the task. And that, even if I have, they don't have the type of minds that are able to follow instructions.
And that would be the case *against* documentation. Now, maybe I've written good documentation and maybe I've written rubbish. But my teammates will never know, because they have no intention of reading it.
As long as the documentation is there, so is the fear that they might have to do this "horrible" task (which is no longer horrible since I redesigned and documented it, but they've only got my word for that). I've introduced the danger that the team might actually have to engage in teamwork, instead of working in isolation from each other. Accountability rears its ugly head.
Fernanda Stickpot
Friday, October 10, 2003
Reginald - you hit on quite a hobby horse of mine in your article, which is documentation being out of step with the actual system. I have never seen (development type) documentation which accurately reflects the truth, the whole truth, and nothing but the truth about a system. I wonder if it is even possible, unless you have a documentation phase after the development is 100% complete. Otherwise the only thing that documents the system is... the source code.
Friday, October 10, 2003
 Recent Topics
Fog Creek Home
|
