September 8, 2012 at 12:45 am
Comments posted to this topic are about the item Document First, Code Later
Best wishes,
Phil Factor
September 8, 2012 at 5:14 am
This is one of those "in a perfect world "scenarios, in my case.
I can see that for large projects, but what about smaller projects or enhancements?
There was a recent article about how most of a developers coding time is used for maintenance and enhancements, and not new coding/projects?
As a developer, too many times to count I've received vague "one line wonder biz descriptions" from the business analysts describing the desired functionality, and it's up to the developer to flesh out the actual requirements, ramifications, the interfaces, the presentation GUIs, and finally document what it was we created.
The #1 problem with that of course, is feature creep: after it gets created from vague biz descriptions, when it finally gets reviews for QA, they jump in and say that's not what they wanted/imagined, and require additional changes...sigh. You can say that's not right, and say "make them fix it", but in the real world, you can only push so hard.
I'd love to get a solid business requirements and documentation like you describe up front for smaller enhancements the same way I would get for large projects.
Lowell
September 8, 2012 at 11:47 am
Sounds nicely politically correct, however, what do you do when the users themselves don't know quite what they want? I run into this a lot - they have a vague idea of what they'd like to achieve, but very little in the way of concrete plans. At some point, pre-production meetings with the users start becoming a rehash of previously stated positions, and no further progress is made in understanding anything. I then create my best guess of what they hope for, and let them start using it. No matter how carefully I follow any plans, there's always loads of things that nobody realized up front, or weren't able to articulate in any comprehensible fashion. If I were to try this method, I would wind up doing much more pointless work, because my documentation of the (yet) unseen interface wouldn't fit the end product anyway.
Creating the app first at least lets me write the documentation only once, and often not at all, because in the process of tuning it, I can build in enough pop-up hints, help screens, tooltips and descriptive captions, based on the users' reactions, that I often don't have to write anything - the end-result app is clear and intuitive enough that new users can start to be effective in it with only a minimum of instruction from a colleague.
Doing it the way recommended in this post would lead to a lot of wasted time and effort, creating documentation that would not only never get read, but of something that never even existed, and never will. I can think of much better uses for my time.
September 8, 2012 at 12:50 pm
Happens to me all the time at work but we're trying to utilize the project management group as part of our regular process. The business knows they must supply requirements to the project manager. If they fail to do so, we weed out the people that really don't want work. It's not perfect but it works and if they comply, we get the requirements we need.
Mark
September 8, 2012 at 1:20 pm
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.
It appears that there is no longer an ability to justify the upfront expense of such a document and we tend to use wireframing to outline, and daub in the required functionality through the simplest possible text. This seems similar to me to what Phil described. Of course at times we do more or less of this kind of specification depending on the circumstance - the one thing you will never see though, as I acknowledge above is a starting document that actually matches the end point. This does not negate the remarkable value I find achieved by at least getting some facts of the design and how it works pinned down in a document of some kind.
September 8, 2012 at 4:54 pm
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.
September 8, 2012 at 8:49 pm
I was on a project once where I told NOT to document something because he/they would never read it.
Later I was criticized because nobody understood my code.
Duh?
September 9, 2012 at 3:36 am
gwardell (9/8/2012)
I was on a project once where I told NOT to document something because he/they would never read it.Later I was criticized because nobody understood my code.
Duh?
The two are not necessarily inconsistent. Documentation and quality of written code are completely separate issues.
September 9, 2012 at 4:36 am
Producing and refining a mock UI up front is invaluable, but be careful to manage user expectations. For many users the UI is the application and they may not understand that there is still work to be done.
September 9, 2012 at 7:09 am
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.
September 9, 2012 at 1:30 pm
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.
September 9, 2012 at 2:49 pm
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.
September 10, 2012 at 2:08 am
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.
September 10, 2012 at 3:50 am
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!
September 10, 2012 at 9:15 am
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.)
Viewing 15 posts - 1 through 15 (of 21 total)
You must be logged in to reply to this topic. Login to reply