January 8, 2009 at 3:16 pm
Documentation is like insurance. You hope it'll never be needed, but if it is needed, you hope you have enough. And you hope the guy whose fault the problem is had enough too.
- Gus "GSquared", RSVP, OODA, MAP, NMVP, FAQ, SAT, SQL, DNA, RNA, UOI, IOU, AM, PM, AD, BC, BCE, USA, UN, CF, ROFL, LOL, ETC
Property of The Thread
"Nobody knows the age of the human race, but everyone agrees it's old enough to know better." - Anon
January 9, 2009 at 11:25 am
Documentation is like an intimate encounter:
1) Not everyone is at the same level of knowledge or expertise
2) The way you prefer it may not be the way others do
3) It's fun at first but can get old real quick when sticking with the same project
4) Takes commitment to truly work in the long run
5) Can produce dire results if not executed properly
6) You may believe it's done but others may feel its incomplete and needs more attention
And In the end
A Bad instance of it is really better then none at all.
Kindest Regards,
Just say No to Facebook!January 9, 2009 at 1:23 pm
A lot of the replies to Steve's original message tend to take the tack of blaming the people who came before us in the chaiin of development/evolution. I sense a fundamental unfairness in this, and to buttress my argument I will cite Fred Brooks's masterpiece "The Mythical Man Month'. To wit, "Any significant program must be written twice -- once to understand the problem, and once to solve it."
I've been in this game 25 years and his principle still holds true. Fancy click IDEs certainly help, but they don't bestow logic, they just find compile errors quickly. Nothing beats analysis+logic+design+code. This combination results in code like J.J. Cale plays guitar -- the fewest possible notes result in the maximal possible result. The mighty Marley had the same idea, and IMO we programmers need to observe and learn from their lessons.
A.
Arthur Fuller
cell: 647-710-1314
Only two businesses refer to their clients as users: drug-dealing and software development.
-- Arthur Fuller
January 9, 2009 at 2:38 pm
fuller.artful (1/9/2009)
A lot of the replies to Steve's original message tend to take the tack of blaming the people who came before us in the chaiin of development/evolution.A.
Wow, that's a totally different interpretation than I got from the posts. I thought people were just using examples from their work to illustrate the point they were making.
Corporate policy has a great deal to do with the importance assigned to documentation, and some of the places I have worked had a policy of "we'll do it later" - and of course later never came. If I give an example of a problem from one of those companies where lack of documentation carried a cost on the backside (at problem research and resolution), that is not blaming the persons who came before me - it's simply stating the consequences of not having an appropriate level of documentation.
What level is appropriate varies by business, but lack of documentation always has a cost associated with in, in my experience. Often, businesses (i.e. managers) don't understand what that cost is (sometimes because IT people are too busy solving the problem to document the cost, but sometimes because IT people don't like to document anything!)
I think I would define an appropriate level of documentation to be: The level that keeps the cost of recovery (or extra development time) below the cost of creating the documentation. You want to see that return on investment. Simple to describe at a high level, but difficult to find that ROI point in reality. Those of us that believe documentation is important are left to try and find the balance point on our own in many cases (some businesses actually do have standards, which helps quite a bit).
At a bank, the level of documentation is typically much higher, because of legal liability issues - customers can get very picky about their money! In a more "customer service" oriented business, there may be more time available to do recovery - days instead of hours - so less specific documentation may be okay.
I found the examples given by various people useful because they indicated effort, which relates to ROI. If it takes you an extra four hours to perform a recovery or upgrade a program, and one-half hour's worth of documentation would have saved you those four hours, then the company just lost your hourly salary * 3.5 in real dollars. Over the course of the year, that could add up to the salary of an additional person - or a retained person.
I hope it's me they retain! :hehe:
Steph Brown
January 9, 2009 at 2:42 pm
Steve Jones - Editor (1/8/2009)
How long did it take you to figure it out, David?
Some of it I didn't figure out, other bits I could remember who was likely to have developed them and what their bad habits were. These let me narrow it down to a list of possible solutions.
I should like to make the point that productive time is lost when people face the distraction of having to trawl through source control and code to find out something that could be summarised in some simple documentation.
In one of my examples people across 3 departments got distracted and it gave the impression that the IT department were a clueless bunch.
I'm all for the web based WIKI and search engine.
It is not the volume that you write its the relevance and clarity that matter.
January 9, 2009 at 3:19 pm
David.Poole (1/9/2009)
It is not the volume that you write its the relevance and clarity that matter.
Yes! Relevance and clarity! Very much so. Organization, too, and not rambling endless verbosity. If a section is verbose, make sure it summarizes in 1 (maybe 2) short sentences the point of the verbosity at the beginning, so the next person does not wade through a lot to potentially find nothing.
Documentation is never perfect, and will always be miserably short of details or examples or case scenarios, or parameters, or, ... etc. But begin at least with a good sectional overview and structure, so that when it does get added to, it is easy to keep updating, somewhat like OOP. Some topics or bits you may find short enough and tightly related enough to be digestible in one topic all together. Others may need full topics for even minor portions to be fully understood.
January 10, 2009 at 11:08 am
Relevance and clarity for sure. That might be sparse documentation IF it's clear.
It also has to be readily available. Which is another problem. Code is easier, but keeping it near the system and also sync'd for DR is an issue. not to mention some of it needs to be offline. 😀
January 11, 2009 at 3:59 am
Wow, that's a totally different interpretation than I got from the posts. I thought people were just using examples from their work to illustrate the point they were making.
You got it right Steph, no-one is trying to blame anyone. That won't help anyway, the job still needs to get done.
Another thing that I also find lacking (me as well) is user manuals for systems developed. I mean, our clients have asked us for manuals but the job always takes precedence over manuals.
:-PManie Verster
Developer
Johannesburg
South Africa
I can do all things through Christ who strengthens me. - Holy Bible
I am a man of fixed and unbending principles, the first of which is to be flexible at all times. - Everett Mckinley Dirkson (Well, I am trying. - Manie Verster)
January 11, 2009 at 8:15 am
Have any of you guys heard of "information mapping"?
I believe it is a trademarked approach. I used to work for a company that produced tehnical manuals and was given a demonstration of it as a technique.
We were given two sheets of A4 with exactly the same relevant pieces of information but the they demonstrated two different layouts.
a. Written as paragraphs as a person would speak it.
b. Layed out in bullet points with tables.
They took exactly the same amount of space, had exactly the same salient facts but the 2nd one let you zero in on the facts straight away whereas the first required careful reading.
I also worked with an information architect who was extremely gifted in the way she structured web-sites. Everything was in a naturally easy to find order and was cross referenced in such a way that nothing was more than two or three clicks away from the home page.
She was so good that a search engine was almost superfluous.
January 11, 2009 at 8:59 am
David.Poole (1/11/2009)
Have any of you guys heard of "information mapping"?
Not by that name, but I do recall discussions in the past about bullet points as a quick way of communicating information. Depending on the document and the information being conveyed, I agree it can make docs easier/quicker to read. (Often quicker to create, too!) I use verbiage if a story needs to be told, and bullet points for areas where clear breakdown is needed, or less detail is required.
It's another tool in the box for us to use. And as far as I know, bullet points aren't trademarked! 😉
Steph Brown
January 11, 2009 at 10:21 am
David,
That's a good point. I think that's what I've learned to do over time just for expediancy's sake.
January 11, 2009 at 11:15 am
Stephanie J Brown (1/11/2009)
David.Poole (1/11/2009)
Have any of you guys heard of "information mapping"?...I use verbiage if a story needs to be told, and bullet points for areas where clear breakdown is needed, or less detail is required.
It's another tool in the box for us to use. And as far as I know, bullet points aren't trademarked! 😉
[font="Tahoma"]In the absence of a doc template, I almost always fall back on the Outline layout. Maybe it was all those years in National Forensics League, but I just find it easier for myself to find it again later that way. In addition if you are using Word and the document is long you get the built in TOC functionality.[/font]
😎 Kate The Great :w00t:
If you don't have time to do it right the first time, where will you find time to do it again?
January 12, 2009 at 7:23 am
I think you have to find a good mix but I think a lot of people get bogged down in documentation more than they should. Over a period of time they tend to develope the taste for documentation at the level they write it and when they don't get that they get frustrated.
To me code is very much the ultimate document and I usually will not read the design documentation of code comments until I review the entire code. My reason for this is once you read the documentation you set your focus on what it should do versus what it is doing. Many times it is a simple mistake such as missing a particular case option. I prefer to find the reaosn for the behavior before looking at the expected behavior.
I personnally think there is a balance between too little documentation and so much that noone cares to ever read. And for those who suggest more documentation is better for junior programmers keep in mind they have to get familiar with code and debugging code so to much can hinder their growth as a coder (IMHO) as they may never be challenged to do better.
September 17, 2014 at 3:08 am
Jack Corbett (1/5/2009)
...I worked for/with an excellent developer who did not document well...
In my opinion, that is an oxymoron. Excellent developers document well. The definition for "document well" is up for debate though...even five years on 😉
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
September 17, 2014 at 3:36 am
The following are a few principles that I try to follow:
FYI I am a big detractor of the programming style where people believe that by careful naming of classes and methods alone is enough code documentation. Naming is essential but is just one of the multiple techniques that should be applied to documentation.
Gaz
-- Stop your grinnin' and drop your linen...they're everywhere!!!
Viewing 15 posts - 61 through 75 (of 89 total)
You must be logged in to reply to this topic. Login to reply