September 10, 2012 at 9:55 am
It's really about trying to balance the documentation as the needs of the users/process change. Your team and functional staff need to determine what documentation is absolutely essential and it should be minimal due to the nature of change in the world we live in today. Documentation is good provided that it is correct, but a working product has more value to your organization.
For one conversion project (COBOL to ASP.NET), our documentation had 6 major revisions (4 before release) and hundreds of minor revisions. Most of the documentation versions in the earlier phases no longer matches the final product. There were new compliance requirements, changes in the enterprise systems and payment process. There was a concrete date that the legacy app would be shut down. If we didn't hit that target date it would cost us substantially to continue the legacy application and we would have to re-write some sub programs within
COBOL to meet our requirements.
So we had thousands of pages of documents, flows, UML, specs, compiled code, unit tests, etc. that were done over 5 years by various staff/consultants (most gone) that no longer apply to the final product.
We couldn't go fully agile, but we finally convinced the CIO, the functional staff and management to go along that route and we salvaged 1/3 of the code and got the project out in time with less staff. Was it perfect when we went live? Nope, but it worked and bugs were triaged quickly. The second phase which was scheduled for a year was released incrementally in under 4 months.
Our source control repository is the documentation. We have standards for check-ins,tasks, bugs, release cycles and comments in the code to tie back to the source control system. We can now extract information from the source control system to build any needed documentation AFTER release. It does require programmers to follow the documentation standards and it isn't perfect by no means, but it works for us.
"There is nothing so useless as doing efficiently that which should not be done at all." - Peter Drucker
September 10, 2012 at 12:04 pm
I've found that documentation before writing a lick of code is actually a pretty easy thing to do. In the early stages, you don't necessarily have to document HOW you're going to do something. You only need to document the functional blocks. It's just like writing comments in code and can be done very quickly. It's sommethinng I'd do even if it wasnn't required because having a plan of attack is worth its weight in gold when it comes time to either design a database or to write code for its usage.
To wit, sometimes all that's needed is a decent flow chart and a bit of narrative to go along with it. Detail can easily be added as time progresses and doing so is no more difficult than the first blush was.
--Jeff Moden
Change is inevitable... Change for the better is not.
September 10, 2012 at 12:43 pm
I agree with the theory. The practice, on the other hand, is a lot harder to implement.
"Can you slap me together a quick prototype? I need to see data in this for it to make sense to me if it's right"... said prototype heads to production a week later.
"Hey, I need a quick page that'll let me access customer data in this way. No, don't worry, it's not a big deal..."... Said page suddenly becomes the core of the new CRM system... and you're never given a chance to redesign around the 4 minute data pull it takes per page.
"How do I know if the report looks right? We don't do widgets and gaskets, I need real numbers." Said report gets slapped together with faked data. "Still, this isn't right, look, the numbers don't..." Fine, so you build the entire damned thing. "Oh, no, we don't need it anymore... it's not blue in background now, it's green. Cancel the entire report request, thanks, we built it in Excel." *blinks*
A shop cannot be hyper-agile and flexible and run under the 'sign every blessed thing' conditions. Larger projects I agree should go through this process... but then the business learns to send down everything in small bites to avoid the necessary paperwork and signoff so they can just get their stuff done without getting stuck in 2 weeks of meetings. They don't want to be there any more than we do.
No, I don't have any 'good' answers to the problem. It's person to person more than tech to issue. Build me any semi-agile system and people will gravitate towards the one where it's not their *** in a sling if it doesn't work. Set everything in stone and 'IT is just impossible to work with!'. Leave it all on the fly and you get a rotting dung-heap. We'll figure it out eventually, I guess.
Never stop learning, even if it hurts. Ego bruises are practically mandatory as you learn unless you've never risked enough to make a mistake.
For better assistance in answering your questions[/url] | Forum Netiquette
For index/tuning help, follow these directions.[/url] |Tally Tables[/url]
Twitter: @AnyWayDBA
September 10, 2012 at 4:31 pm
The last end-user documentation I ever read was for SuperCalc. It was a long time ago, but that was how I taught myself about spreadsheets.
Leonard
Madison, WI
September 10, 2012 at 7:36 pm
Evil Kraig F (9/10/2012)
I agree with the theory. The practice, on the other hand, is a lot harder to implement."Can you slap me together a quick prototype? I need to see data in this for it to make sense to me if it's right"... said prototype heads to production a week later.
"Hey, I need a quick page that'll let me access customer data in this way. No, don't worry, it's not a big deal..."... Said page suddenly becomes the core of the new CRM system... and you're never given a chance to redesign around the 4 minute data pull it takes per page.
"How do I know if the report looks right? We don't do widgets and gaskets, I need real numbers." Said report gets slapped together with faked data. "Still, this isn't right, look, the numbers don't..." Fine, so you build the entire damned thing. "Oh, no, we don't need it anymore... it's not blue in background now, it's green. Cancel the entire report request, thanks, we built it in Excel." *blinks*
A shop cannot be hyper-agile and flexible and run under the 'sign every blessed thing' conditions. Larger projects I agree should go through this process... but then the business learns to send down everything in small bites to avoid the necessary paperwork and signoff so they can just get their stuff done without getting stuck in 2 weeks of meetings. They don't want to be there any more than we do.
No, I don't have any 'good' answers to the problem. It's person to person more than tech to issue. Build me any semi-agile system and people will gravitate towards the one where it's not their *** in a sling if it doesn't work. Set everything in stone and 'IT is just impossible to work with!'. Leave it all on the fly and you get a rotting dung-heap. We'll figure it out eventually, I guess.
Agreed. There exists a balance somewhere between "paralysis by analysis" and "have it your way fast food".
--Jeff Moden
Change is inevitable... Change for the better is not.
September 11, 2012 at 10:11 am
Hm. I certainly try to document as much of my coding as I can manage at my current workplace, but I could certainly understand the feelings of futility some people have in regards to the matter :-). Wrote up a new method to calculate shipping rates awhile back, and recently added some more error-checking functionality to it. The error-check form has handy bits written on it about what errors would usually show up, and how to handle them, which would usually take less than 15 seconds to fix. I came in yesterday morning to the owner saying there was an error with the rate calculator, and could I please handle it. It was the very first error documented on the form, which just required a deletion from that same form :crazy:
Still, documentation's definitely a wonderful thing; I fully understand the need to do so, either before or after a project (ideally beforehand, but that can be a bit too idealistic). The point's driven home all the more when I look at vendor coding that doesn't have documentation, or the documentation is from several versions ago and doesn't cover new core operations. Quite painful!
- 😀
September 11, 2012 at 10:55 am
As well as helping others who have to maintain your work, documenting something is a great way of crystallizing and 'unit-testing' your own understanding of the process you are going to automate. I don't much care whether anyone ever reads my documentation: Once it is written, it has already proven its worth in avoiding all those mistakes. If anyone reads it, it is an unexpected bonus. As I said in the editorial, a good user-documentation is great for tying down the estimates of development time. For any professional developer, being able to say accurately how long a job will take is a way to a long and successful career.
In the days when applications were expected to have proper documentation, Microsoft produced a TSQL programming manual for SQL Server (I think it was version 6) It was wonderful, brief, simple, but comprehensive; and I remember marveling at its clarity. I read it over and over again, marveling at how little I remembered of the last reading, until a colleague stole it. Come to think of it, he might have merely been reclaiming his property, but I resented it when I lost it.
Best wishes,
Phil Factor
Viewing 7 posts - 16 through 21 (of 21 total)
You must be logged in to reply to this topic. Login to reply