Documenting Design: Tedious, Time Consuming and Absolutely Necessary
I have been writing quite a lot of documentation lately, and to be honest, I hate it. It is tedious, time consuming and I have a suspicion that no one will read it, so what is the point? I am sure there are developers out there who enjoy documenting their designs, but I suspect that they are rarer than hen’s teeth.
All this said, I know from experience that there are significant benefits to having documented designs. For example, I can cite situations where having a documented design before I cut code saved time because the design had been proved ‘on paper’, where other teams on the project had to go through several revisions to get to the same point with their code.
So what is your experience? Have you had situations where design documentation was useful? Or do you feel that it is always a waste of time?
I am also interested in what tools or methodologies people use for their Domino designs. Anyone use UML? Does anyone remember the Lotus AVM?
Oh well, back to the documentation. Hang on a minute though, I think those pencils need sharpening…
All this said, I know from experience that there are significant benefits to having documented designs. For example, I can cite situations where having a documented design before I cut code saved time because the design had been proved ‘on paper’, where other teams on the project had to go through several revisions to get to the same point with their code.
So what is your experience? Have you had situations where design documentation was useful? Or do you feel that it is always a waste of time?
I am also interested in what tools or methodologies people use for their Domino designs. Anyone use UML? Does anyone remember the Lotus AVM?
Oh well, back to the documentation. Hang on a minute though, I think those pencils need sharpening…
Category Design Application Development Best Practices
| Permalink |
|
|
|
|
|
Comments
Now I think you need documentation .. but I often find that high level object (or higher) type documentation is enough. E.g. you can't write enough documentation to explain the http post error the user just phoned in with but if you at least know the system makes a call to a web server at least you know where to start looking (and chances are that the web server is down or slow).
It might also depend on the sort of product you are producing - a single app for 10 users or an ERP system for thousands?
So I don't think there is a straight answer to this but I think I could guarantee something: You'll never write enough documentation to cover every angle and lot of the documentation will go unread by most. So on that basis write 'just enough'
Posted by Scott At 08:10:58 PM On 04/02/2008 | - Website - |