|
Case against documentation?
Going off topic from the documentation hiring question thread...
Fernanda Stickpot:
"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."
It's really good to know I'm not the only one who feels like I'm wasting time writing documentation. I think it ought to be done, I'd rather do it, but yeah, in the end it's wasted effort *if no one reads it*. And it [never improves / starts to go stale and bitter] if no one reads it, just like code that's never been executed will have more bugs than the code that's used every day.
People fear what they don't understand, they don't use it or maintain it, it goes stale. Eventually you have dead code (not used, but still taking up space and causing confusion) or zombie code (still used, but it's not "alive" -- and you don't know what provocation will cause it to rise up and go on a killing rampage). It seems like documentation is dangerous because it's never really dead -- if you're reading it, that's the original intended usage. So it's either alive and helpful, or alive and trying to suck out your brains through a straw, and as a user you can't immediately tell the difference.
Is this observation just another argument for YAGNI, or is there actually something we can do as we see documentation or code in our organization that's just starting to die? And how, in a bureaucratic organization or in dealings with one, do you make the case *against* documentation that won't stay alive?
Mikayla
Friday, October 10, 2003
Documentation is no different than code. If you
can't write good code or maintain it then you
won't for documentation.
Try as you might you cannot encode the intent,
the background behind your code in names. And
this is the stuff that people need later to make
decisions on how to make changes. Why did
you do it this way? What will happen if i need
to do X? This is where we get killed in maintenance.
logically incorrect
Friday, October 10, 2003
You are so right. So many people start out writing documentation for a custom system like they're documenting an API ("FunctionA takes two parameters of type X and Y, and returns type Z"). No shit, Sherlock. I can read source code...
When what you really want are records of the design decisions that they made in building the system.
Having said that, after I write my real documentation, I always use an automated tool to spew out all the function definitions and such, to bulk it up, and make it look more like an "A" paper ;)
Rob VH
Friday, October 10, 2003
Are we talking end-user documentation or developer documentation?
I'll assume we're talking developer documentation.
I've already mentioned the difference between functional and compliance documentation so I'll again assume we're talking about functional documentation.
What's the point of functional documentation? I would say it is intended to convey information such that a task can be accomplished.
But if you already have good lines of communication in your team and information is flowing, why do you need documents?
Documents are a much less desirable form of communication compared to conversation. Very few of us would prefer to read something when they can ask a simple question, which is why help lines exist. Conversation has a way of focusing on areas where information is lacking while ignoring areas where there is already enough information. Documents just spam you with everything.
People are current. Documents are not. I trust the developer working on the code far more than I would ever trust a design document. Especially one 3 months old.
Now, wait a minute. This is not a call to get rid of all documentation. There are cases where documentation does add value.
Simply put, the usefullness of documentation is directly related to the stability of the system it documents. API's are very stable and so documentation for them is quite useful (some would say necessasry). Designs for software are much less stable and therefore the value of documentation is diminished.
What is more valuable for dynamic system are simple models which can be quickly discarded or updated. A UML diagram on a napkin is perfect. A couple of pages describing an interface is great. The level of effort invested should be proportional to the expected lifespan of the contents of the document.
So the argument is not black and white, documentation vs no documentation. It's more about realizing what level of documentation is appropriate for the current circumstances.
anon
Friday, October 10, 2003
"Cases" against documentation:
Academically and bureaucratically leaning environments where jaw-flapping, theorizing, and pontificating are regarded as more important than doing actual development.
Environments where the management pushes for documentation as a magic bullet to make a hypothetical "any decent programmer" fluent in the project internals. A close cousin to outsourcing pressure, since it seeks to find ways to eliminate bodies that are actually necessary.
Any developer who has less actual skill than the job demands, who buries himself in "designs" as a distraction from work to be done.
A lead who grinds out pounds of turgid documentation with the intention of throwing it over the wall to other developers. IE, getting stupid and/or avoidance about the need to communicate one on one.
Mainly, the cases against documentation are overuse and misuse. Too much and/or extraneous documentation can be as bad as not enough docs because outsiders will not be able to distinguish "fluff" from actual substance. (I'm one of those people who believes that too much information is as bad as not enough.)
Bored Bystander
Friday, October 10, 2003
I love how these conversations start out with, "We don't have a good development process in place, and it's too hard to fix our development process, so let's ignore part of the development process and hope it goes away."
OK. I'm being a little sarcastic here, but the point is not whether you can have a few water cooler conversations throughout the day and get the product built. That's easy.
But what happens when the development team rolls over? What happens when you hire a new team member?
All of those wonderful conversations are completely useless in conveying information to the new hires, unless the team members want to sit down and attempt to remember everything they've talked about for the past 8 months. Not to mention the fact that the human brain is horrible at remembering details. And I don't need to point out that software development is terribly detailed.
I think Rob hit the nail on the head. It's not as important to document every single routine in the system in UML, down to every single private function in every single class. What is important is documenting how the detailed design satisfies the functional requirements, as well as defining the public interface on those objects that collaborate to satisfy the functional requirements. Documenting the decision-making process helps out a lot as well.
THAT, combined with the water cooler conversations to hammer out the private implementation details and to clarify any misunderstandings, in my humble opinion, is the right approach.
So, what's the right amount of documentation? To me, it's enough to satisfy the following requirements:
1. A developer can understand how certain objects collaborate to satisfy the functional specification, and which objects they are.
2. A reviewer can validate that the functional requirements are actually satisfied by the detailed design, before one line of code is written.
3. A new team member tasked with maintaining or enhancing existing code can understand the "big picture" fo how the code is organized. From there, and from reading comments in the code, he or she can fully understand how the system works.
There is no "right level" of documentation, in my opinion, because that varies from project to project. However, I believe that the requirements I outlined above (along with others I'm not even thinking of, I'm sure), are invariant for any project of considerable complexity.
<disclaimer>
My experience has been limited to fairly large shrink-wrap projects (10 to 20 man-years of effort, with typical lifetimes of 5 to 10 years), and I've been bitten by the "we'll wing it with less documentation" idea. It just doesn't work for large projects bound for thousands of end-users. So I'm a bid jaded. I'm sure smaller projects with shorter lifetimes can get away with less formalized documentation.
</disclaimer>
Dave
Dave
Friday, October 10, 2003
[All of those wonderful conversations are completely useless in conveying information to the new hires, unless the team members want to sit down and attempt to remember everything they've talked about for the past 8 months. Not to mention the fact that the human brain is horrible at remembering details. And I don't need to point out that software development is terribly detailed.]
Well, we pair program. Our latest new developer was working on new stories 2 days after being hired. After 3 iterations, he's contributing fully. Take of that what you will.
Your argument is flawed. You wouldn't take a new hire and drop 8 months of documentation on his desk and expect them to read it all before working would you? Maybe you would. I would prefer to have the developer get close to the code, working with someone senior, and learn gradually while at the same time contributing.
anon
Friday, October 10, 2003
My simple rule:
Everytime i make a decision i document it, why i made
it, and any implications if it is violated.
We work in complex real-time multi-threaded invironments.
The consequence of just using a mutex in the wrong
place can be huge. The runtime characteristics of
code are usually not at all abvious from the flat
text representation, so you need to convery that
somehow.
Just yesterday there was some code where i didn't do
this, there was a bug or difference of opinion of why
it worked that way, and i couldn't remember
at all why. If you work years and years it's
impossible to remember everything.
The source code may or may not be the design. But the
source certainly is your memory.
logically incorrect
Friday, October 10, 2003
[I've been bitten by the "we'll wing it with less documentation" idea]
I think you miss the point here as well. The point is not to simply stop doing documentation, the point is to decide how much documentation you need.
Just to go back to the original poster, if someone is cranking out documentation that the developers aren't using, why continue? Clearly the developers do not NEED it. It's waste.
Please don't confuse the desire to reduce wasted effort with throwing your process out the window. If your process depends on heaping piles of documentation perhaps you need to re-examine your process.
anon
Friday, October 10, 2003
Or, alternately, maybe you need the documentation.
There are cases where heaps of documentation are necessary (I'm in one). There are many, many cases where it's not necessary.
I would ask yourself: What would happen if we didn't have this documentation?
The Pedant, Brent P. Newhall
Friday, October 10, 2003
[Or, alternately, maybe you need the documentation.]
Sure. Absolutely. The projects we work on are far too varied to come up with a hard and fast rule.
All I'm saying is that the question of the amount of documentation needed has nothing to do with the process of the team, or the quality of the final product.
The only general statement I think you can make is that you don't want more documentation than you absolutely need.
anon
Friday, October 10, 2003
Anon (response 1) - The new developer wouldn't be reading 8 months of documentation, he (or she) would be reading a small part of the documenation, that may have been created 8 months ago. By allowing the documentation to convey the majority of the information the new hire needs to know, it frees the other team members from having to babysit the new hire.
The idea is to leverage personal interaction for clarification only, not for conveying all information from step 1, as well as being tied down as the only resource to convey the information. I've tried it both ways, and the former has worked in a far superior manner.
Anon (response 2): You are actually highlighting my point exactly, which is that the level of documentation required for a project varies, depending upon the project.
I was only pointing out that regardless of the level of documentation, there are certain requirements that the documentation must fulfill (based upon my experience, with our products--but I feel they are not unique to our situation).
This is the "acid test" to tell you whether you have enough documentation. If you are going way above and beyond what is required to meet the test, then you are probably doing too much.
Dave
Dave
Friday, October 10, 2003
One thing my team does about documentation is to try to generate it "just in time." When someone asks a question, we write it and the answer to it down on a Wiki. One of the guys built a nice mechanism for categorizing the material so that it's easy to browse by topic, use-case, class, lifecycle phase, and so on. As a couple of you mentioned above, the ones I find most valuable are the ones that answer the question, "Why did you...?" I also like the ones that answer the question "How do I...?" since these give guidance for extending the system. Since it's on a Wiki it's really easy for me to link one article to another, or make other changes that improve things. I can also link out to other web sites for things like descriptions of algorithms or policy documents from the business units the software will serve. The category thing makes it easy to find pages that need to be updated as you change the system.
There's a few improvements that I can think of, but in general this system seems to be a fair balance between generating too much documentation or not enough documentation. We're not creating reams of it in the hope that something in there will be someday useful, but we're also not flying blind.
Wikid
Friday, October 10, 2003
I'll second the recommendation for a wiki. They're a great, central repository for a lot of team/project information.
anon
Friday, October 10, 2003
I deal with Configuration Management and the case for documentation is very clearly spelled out. (If you look at the IEEE standards for CM it even classifies the code itself as 'documentation' as it is something that describes the Configuration Item - the end product. Personally I think this is bollocks but there you go!)
What should you document?
Requirements. Absolutely. Otherwise how the hell do you know what you're supposed to be building. And how else do you manage change to them
Design. Absolutely. The design or architecture is the 'big picture' and you don't get this by reading code alone and usually a single developer won't know it all.
I like the idea about documenting decisions. When I've been developing on my own a year down the road I find it hard to remember why I did something a certain way... and that's not even the problem of trying to understand why someone else did something! Luckily I can go back to the notebook volumes that I scribble in and usually find a clue as to what I did. It's not neat... and it's not stored on the PC.. but I am the only developer so I think I can be afforded that minor working indiscretion. When the product is finished I'll get the docs all typed in.
I have been thinking about getting a drawing tablet so that instead of scribbling in a book I can scribble and amend electronic notes. Still not neat but it's a lot easier to hand draw a little diagram (e.g. a couple of minutes) than trying to draw it well in Vision (30 minutes)...
I thought about a tablet PC for general scribbling but the main problem is that I can open by hard back notepad, scribble a thought and close it again all in the space of a few seconds. If I had a tablet PC I'd have to fire it up, wait for it to be ready before I can write that single thought down. I'm tempted but it's a lot of money to invest in something that I end up leaving in the office and still take my hard backed notepad around with me...
Gwyn
Friday, October 10, 2003
I often scan my notebook pages to capture my scribbles because I have never had a drawing program that I liked. Takes forever to use those things. I even do this with many presentations that don't require a lot of polish because PowerPoint seems to be beyond me.
RJP
Friday, October 10, 2003
Towards some hard and fast rules for documentation:
1. Will I be able to work without this doc?
2. Will I be able to work WELL without this doc? Will writing it make my task loads clearer and easier, even if I could muddle through without it?
3. Will others be able to work on this project without this doc?
4. Will others be able to work WELL on this project without this doc?
5. Would it be a good idea for legal, political, or financial reasons to have a written record of what I did and why?
If the answers to questions 1-4 are YES, go to Q5. It's unfortunate to have to consider Q5, but that's life. Q5 is the tiebreaker.
If the answers to questions 1-3 are YES, Q4 is your tiebreaker, followed by Q5.
If the answers to any of the above questions are NO, go ahead and write just enough.
If you have a compliance document to write, fill in just enough and use hyperlinks to link to the meaningful content in the proper documents you wrote yourself.
Fernanda Stickpot
Friday, October 10, 2003
I disagree that conversation is better than documentation.
Example:
The junior developer can spend a minute looking up the API to a commonly used function.
or... he can spend half a minute interrupting the Senior Developer who is deeply immersed in thought about the subtleties of an important design decision, and ask the Senior Developer to tell him how the function works.
To the Junior developer level person, conversation seems a great idea. He has saved 30 seconds and not had to bother with pesky reading or looking up skills!
To the indispensible Senior Developer whose flow was just broken and who has just lost the key critical insight that he had been pursuing for over an hour because of the laziness and incompetance of the Junior developer, conversation is not better than documentation.
Dennis Atkins
Friday, October 10, 2003
[The junior developer can spend a minute looking up the API to a commonly used function.
]
Didn't I say that API's, by the grace of their stability, are clearly cases where documentation is valuable?
anon
Friday, October 10, 2003
For externally created APIs, It's not their grace and elegance but the fact that you ain't got the source code. And even if you do got it, you shouldn't be looking at it -- if the library is any good at all, implementation details should be well hidden and irrelevant to use.
Developers should not be asking other developers how to use a function. That is a break in flaw and waste of time. Besides, who is to say the original developer is even there any more, or if he is that he remembers how he did something 2 years ago. ALL that stuff needs to be documented. If not documented, then the guy trying to use it should write the docs himself then and there rather than bother the other engineers. Only if there is some true difficulty should others be bothered. People need to learn to do their own work and not expect others to do it. Programmers who need to be coddled and led by the hand along the primrose path should go work in some other field because their constant inturruptions and inane questions they could have answered themselves are a serious drain on the productivity of the folks who are doing the real work.
Dennis Atkins
Friday, October 10, 2003
Say, that's a real nice strawman you've built there.
When I said that conversation was more information rich than documentation, did I really need to mention the caveat that developers should probably just look it up if the reference is readily available?
Again, I guess my work experience is totally different from most of you here. I've never worked on a team that was so broken the first thing you think about when someone says "talk" is that it's going to break up your flow and that other programmers shouldn't be coddled. I kinda thought we could just let common sense cover obvious cases such as looking up a function definition. Apologies for making that assumption.
anon
Friday, October 10, 2003
 Recent Topics
Fog Creek Home
|
