Click here to monitor SSC
SQLServerCentral is supported by Redgate
 
Log in  ::  Register  ::  Not logged in
 
 
 


The Details are in the Small Print


The Details are in the Small Print

Author
Message
Phil Factor
Phil Factor
SSCommitted
SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)SSCommitted (1.5K reputation)

Group: General Forum Members
Points: 1501 Visits: 2968
Comments posted to this topic are about the item The Details are in the Small Print


Best wishes,

Phil Factor
Simple Talk
mosaic-287947
mosaic-287947
SSC Veteran
SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)SSC Veteran (249 reputation)

Group: General Forum Members
Points: 249 Visits: 825
I once had to update an ancient Visual Basic 4 (yes, that is not a typo) application. The code had gone through many versions and was littered with comments about what each function did and much more besides. There were way more comments than actual code. Very daunting to read for the first time.
***BUT*** when it came to doing the update, those comments made all the difference and helped enormously. I learned a lot from that ancient programmer. And that project is the reason that these days, when I spend more than(say) 10 minutes struggling to get a statement just right I often add a comment so that the next person won't have to figure it out all over again (that person could well be me a few months later). Clever one-liners are fine for a one-off throw-away situation (and oh so satisfying), but for code that must run over and over again, comments are more important than elegance.
David.Poole
David.Poole
SSCertifiable
SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)SSCertifiable (6.1K reputation)

Group: General Forum Members
Points: 6077 Visits: 3238
I think one of the problems is that we all know good documentation when we see it but the definition of good documentation is elusive.

The art of writing documentation is an unrecognised skill. The skill is in boiling something complicated down into an easily digested piece of information. If you have the skill then your output will be so simple as to underrepresent the effort required to write it

LinkedIn Profile

Newbie on www.simple-talk.com
Eric M Russell
Eric M Russell
SSCrazy Eights
SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)

Group: General Forum Members
Points: 9749 Visits: 10359
I assume we're talking about the need for the developers to create technical and operational documentation here, since the business should be exclusively providing the requirements documentation, at least collaborating with the developer on functional specifications, and then the business exclusively provides the end user documentation.


"The universe is complicated and for the most part beyond your control, but your life is only as complicated as you choose it to be."
dstrickrott
dstrickrott
Say Hey Kid
Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)Say Hey Kid (669 reputation)

Group: General Forum Members
Points: 669 Visits: 888
"Sure, there are many more exciting activities in life,but if you can master the art of writing the whole range of documentation thatunderlies the development and upkeep of modern business systems in the typical enterprise, then you are greatly empowered."

Some of my best documents that I still refer to on occasion are functional specs I've written for contract developers. Those must be exact and nearly perfect or you won't get the system you want without, typically, more $$.

Gary Varga
Gary Varga
SSChampion
SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)SSChampion (13K reputation)

Group: General Forum Members
Points: 13703 Visits: 6467
Phil Factor - Friday, March 10, 2017 6:29 PM
...Others delude themselves with the belief that their code is 'self-documenting'...

Is it coincidence that these people are often not the best communicators anyway? In my experience the majority of people who believe their code is self-documenting will, when asked a question, repeatedly suggest that you read their code. Even if they already know that you have.


Gaz

-- Stop your grinnin' and drop your linen...they're everywhere!!!
Eric M Russell
Eric M Russell
SSCrazy Eights
SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)SSCrazy Eights (9.7K reputation)

Group: General Forum Members
Points: 9749 Visits: 10359
Gary Varga - Wednesday, March 15, 2017 8:56 AM
Phil Factor - Friday, March 10, 2017 6:29 PM
...Others delude themselves with the belief that their code is 'self-documenting'...

Is it coincidence that these people are often not the best communicators anyway? In my experience the majority of people who believe their code is self-documenting will, when asked a question, repeatedly suggest that you read their code. Even if they already know that you have.

Pairing up two developers who both believe their code is self-documenting; that is poetic justice.



"The universe is complicated and for the most part beyond your control, but your life is only as complicated as you choose it to be."
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