SQL Clone
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


Document First, Code Later


Document First, Code Later

Author
Message
Phil Factor
Phil Factor
SSCertifiable
SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)SSCertifiable (7.5K reputation)

Group: General Forum Members
Points: 7494 Visits: 3064
Comments posted to this topic are about the item Document First, Code Later


Best wishes,

Phil Factor
Simple Talk
Lowell
Lowell
SSC Guru
SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)SSC Guru (138K reputation)

Group: General Forum Members
Points: 138961 Visits: 41521
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
--help us help you! If you post a question, make sure you include a CREATE TABLE... statement and INSERT INTO... statement into that table to give the volunteers here representative data. with your description of the problem, we can provide a tested, verifiable solution to your question! asking the question the right way gets you a tested answer the fastest way possible!
pdanes
pdanes
Hall of Fame
Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)

Group: General Forum Members
Points: 3144 Visits: 1366
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.
Mark Eckeard
Mark Eckeard
Ten Centuries
Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)Ten Centuries (1.3K reputation)

Group: General Forum Members
Points: 1295 Visits: 505
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



call.copse
call.copse
SSCertifiable
SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)SSCertifiable (7.4K reputation)

Group: General Forum Members
Points: 7446 Visits: 2089
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.
bitbucket-25253
bitbucket-25253
One Orange Chip
One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)One Orange Chip (26K reputation)

Group: General Forum Members
Points: 26879 Visits: 25280
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.

If everything seems to be going well, you have obviously overlooked something.

Ron

Please help us, help you -before posting a question please read

Before posting a performance problem please read
gwardell
gwardell
Grasshopper
Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)

Group: General Forum Members
Points: 11 Visits: 34
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?
pdanes
pdanes
Hall of Fame
Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)Hall of Fame (3.1K reputation)

Group: General Forum Members
Points: 3144 Visits: 1366
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.
mosaic-287947
mosaic-287947
SSC-Addicted
SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)SSC-Addicted (439 reputation)

Group: General Forum Members
Points: 439 Visits: 849
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.
gwardell
gwardell
Grasshopper
Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)Grasshopper (11 reputation)

Group: General Forum Members
Points: 11 Visits: 34
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.
Go


Permissions

You can't post new topics.
You can't post topic replies.
You can't post new polls.
You can't post replies to polls.
You can't edit your own topics.
You can't delete your own topics.
You can't edit other topics.
You can't delete other topics.
You can't edit your own posts.
You can't edit other posts.
You can't delete your own posts.
You can't delete other posts.
You can't post events.
You can't edit your own events.
You can't edit other events.
You can't delete your own events.
You can't delete other events.
You can't send private messages.
You can't send emails.
You can read topics.
You can't vote in polls.
You can't upload attachments.
You can download attachments.
You can't post HTML code.
You can't edit HTML code.
You can't post IFCode.
You can't post JavaScript.
You can post emoticons.
You can't post or upload images.

Select a forum







































































































































































SQLServerCentral


Search