Click here to monitor SSC
SQLServerCentral is supported by Red Gate Software Ltd.
 
Log in  ::  Register  ::  Not logged in
 
 
 
        
Home       Members    Calendar    Who's On


Add to briefcase ««123»»

Document First, Code Later Expand / Collapse
Author
Message
Posted Sunday, September 09, 2012 1:30 PM


Old Hand

Old HandOld HandOld HandOld HandOld HandOld HandOld HandOld Hand

Group: General Forum Members
Last Login: Friday, March 07, 2014 2:20 PM
Points: 308, Visits: 862
gwardell (9/9/2012)
I worked once on a government contract where the entire application was fleshed out in a design tool. That "application" wound up being the deliverable and the application never made it into a real language.
Potemkin village, eh? Didn't anyone notice or care that the application didn't do anything?

But if the 'users' were satisfied, what the heck. Might even be a way to save on development costs, and the maintenance would certainly be simple.
Post #1356504
Posted Sunday, September 09, 2012 2:49 PM
Forum Newbie

Forum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum NewbieForum Newbie

Group: General Forum Members
Last Login: Monday, September 17, 2012 7:34 AM
Points: 7, Visits: 30
pdanes (9/9/2012)
gwardell (9/9/2012)
I worked once on a government contract where the entire application was fleshed out in a design tool. That "application" wound up being the deliverable and the application never made it into a real language.
Potemkin village, eh? Didn't anyone notice or care that the application didn't do anything?

But if the 'users' were satisfied, what the heck. Might even be a way to save on development costs, and the maintenance would certainly be simple.


It did stuff, it actually updated the database, it was just horribly slow.

I guess it was one of the first 4GL RAD systems.
Post #1356509
Posted Monday, September 10, 2012 2:08 AM
SSCrazy

SSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazySSCrazy

Group: General Forum Members
Last Login: Today @ 6:57 AM
Points: 2,862, Visits: 1,702
Some how we have to get to a meeting of minds. I know what I consider documentation and I have consistently said that if I am called up at 3am in a decaffeinated state after nursing a sick toddler the documentation has to be sufficient to resolve a production issue.

That said, if the requirements are not written in sufficient detail then how can developers write suitable tests for test/business driven development?

Are developers the right people to write documentation? Should there be a job role that sits somewhere between development and business analysts that produced the documentation?

There is a principle of "if it hurts, do it more often". You'd think that the development community would have applied their brains to this.

I think the problem lies in that business users actually use the end product of software and the idea that continuous integration increases quality and (possibly) speed of delivery is something they can buy into.
Technical documentation is something they will never read or see so if the development community whinge about doing it the business is not going to crack the whip to get it done.

There is nothing like a healthy dose of outsourcing to shine a glaring light on the inability to write decent requirements. Every change costs money, the costs can't be lost in internal bureaucracy.


LinkedIn Profile
Newbie on www.simple-talk.com
Post #1356590
Posted Monday, September 10, 2012 3:50 AM


UDP Broadcaster

UDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP BroadcasterUDP Broadcaster

Group: General Forum Members
Last Login: Today @ 10:47 AM
Points: 1,488, Visits: 974
bitbucket-25253 (9/8/2012)
call.copse (9/8/2012)
I think I have followed a similar trajectory to Phil. I have spent (literally) years writing specifications in the olden days. We spent approximately 40% on the project time on such. Of course by the time things were actually done they diverged wildly from the original - it is certainly true that on any sizable project you will find any number of previously forgotten issues.


We used the document then code method with:
The documentation was reviewed by the user(s), and the last page held a sign off block which simply stated, "I (we) have reviewed this specification on (fill in date and time) and find it to be an accurate statement of the work required and the required results of said work"

on any sizable project you will find any number of previously forgotten issues
in which case as the items were found the document was updated with the solution of forgotten issues and again an additional sign off block which simply stated, "I (we) have reviewed this specification on (fill in date and time) and find it to be an accurate statement of the work required and the required results of said work"

I find that today's business culture does not properly measure the cost of doing things over and over ... the old idea of measure twice cut once seems to have disappeared.
And miracle of miracles the $$$ required are always found to do it over and over and over and over.


I'm with you pretty much.

The problem we always had with getting a 'one true document' was that because we always wrote the addendums as a possiblity to be updated as required, and there were often quite a few, and the actual implementation became slightly divergent when true needs became apparent perhaps even from our side (better way to go) you had to fold in minor changes, potential updates and so forth into one big document. It can work fine of course but the folding in was basically the last priority. I have since those times worked with good PMs who actually do that sort of thing leaving you to get the functionality right - bliss!
Post #1356620
Posted Monday, September 10, 2012 9:15 AM
SSC-Enthusiastic

SSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-EnthusiasticSSC-Enthusiastic

Group: General Forum Members
Last Login: Tuesday, April 01, 2014 3:27 PM
Points: 115, Visits: 957
The customer who doesn't know what they want:
http://dilbert.com/strips/comic/2006-01-29/

I'm a "grey beard" and I've run my own shop several times. I've always insisted on detailed specifications, signed off by the customer, before development work begins (we don't count prototyping as development work). I had a sales geek grouse once about "how much time it was taking to design the thing, why can't we just do it?" When the next project came in, I let him run with it and "just do it." Afterwards -- after all the carnage, scopus creepus maximus, missed dates, gross budget overruns, etc. -- he came to me and said, "OK, point taken, we should always get specs signed off at the beginning." Experience has shown me that people who "just do it" are spending more time on a project than if the scope/requirements/sign-off steps are followed.

The Business Analyst should always be getting the scope, requirements, and high-level design done before handing it off to the development team. The developer should be responsible for the details*. In terms of SQL, I document what kind of data is to be captured and approximately how much of it is coming in, and the DBA and developer team up to determine the types and sizes...the details.

Hopefully everyone has seen the classic "what the customer wanted" drawings (they wanted a tire swing, got a barcalounger hung from steel girders) and it shows how important it is that everyone is on the same page, singing the same hymn, at the same stanza and note.

(* - Although one time I was a BA for a hospital system shop and we had a mainframe Y2K project outsourced to India, and they couldn't figure out what had to be done and insisted on a detailed specification document with the specific changes we wanted. I had to, for each of the 140+ CICS and batch COBOL programs, list the row number where the code to be changed was found and show the before and after changes. I pointed out to the VP of development that if I was going into each program anyway and document the changes, why not have me make the changes and be done with it? Turns out the CEO "had read a magazine" and wanted an outsourcing firm to do the "menial" tasks and no amount of logic could change his mind. Needless to say we spent a lot of time and money to get specifications for someone who should never have been allowed near the code in the first place.)
Post #1356815
Posted Monday, September 10, 2012 9:55 AM
SSC Rookie

SSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC RookieSSC Rookie

Group: General Forum Members
Last Login: Sunday, February 23, 2014 8:23 AM
Points: 30, Visits: 163
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
Post #1356853
Posted Monday, September 10, 2012 12:04 PM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 5:41 PM
Points: 35,944, Visits: 30,229
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
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

"Change is inevitable. Change for the better is not." -- 04 August 2013
(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #1356937
Posted Monday, September 10, 2012 12:43 PM


SSCertifiable

SSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiableSSCertifiable

Group: General Forum Members
Last Login: Saturday, April 12, 2014 12:51 AM
Points: 5,986, Visits: 6,930
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.



- Craig Farrell

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 | Forum Netiquette
For index/tuning help, follow these directions. |Tally Tables

Twitter: @AnyWayDBA
Post #1356959
Posted Monday, September 10, 2012 4:31 PM


SSC Veteran

SSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC VeteranSSC Veteran

Group: General Forum Members
Last Login: Today @ 11:12 AM
Points: 266, Visits: 1,191
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
Post #1357054
Posted Monday, September 10, 2012 7:36 PM


SSC-Dedicated

SSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-DedicatedSSC-Dedicated

Group: General Forum Members
Last Login: Today @ 5:41 PM
Points: 35,944, Visits: 30,229
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
"RBAR is pronounced "ree-bar" and is a "Modenism" for "Row-By-Agonizing-Row".

First step towards the paradigm shift of writing Set Based code:
Stop thinking about what you want to do to a row... think, instead, of what you want to do to a column."

"Change is inevitable. Change for the better is not." -- 04 August 2013
(play on words) "Just because you CAN do something in T-SQL, doesn't mean you SHOULDN'T." --22 Aug 2013

Helpful Links:
How to post code problems
How to post performance problems
Post #1357087
« Prev Topic | Next Topic »

Add to briefcase ««123»»

Permissions Expand / Collapse