Abstract: Tech Writing for Techies

  • Ray K

    SSC-Dedicated

    Points: 31037

    Ugh. I've been turned down to speak in Ottawa and Maine. 🙁

    I should know about Rochester in a few weeks, and in lieu of Maine, I've applied to speak in Philadephia instead. Let's see what happens.

    +--------------------------------------------------------------------------------------+
    Check out my blog at https://pianorayk.wordpress.com/

  • Ray K

    SSC-Dedicated

    Points: 31037

    I presented this last night at my monthly SQL user group meeting, and it went VERY well!!! People told me they enjoyed it! And I knew I had a successful presentation when about 15-20 minutes of unprompted discussion followed it!

    Hopefully, the folks at the SQL Saturdays to which I submitted it will think highly enough of it to schedule it!

    +--------------------------------------------------------------------------------------+
    Check out my blog at https://pianorayk.wordpress.com/

  • Jeff Moden

    SSC Guru

    Points: 994284

    Ray K - Thursday, February 4, 2016 9:12 AM

    Jeff Moden (1/28/2016)


    I've found that many technologists that are in the business of writing code don't understand the extreme ROI of commenting code properly. In a previous company where no code was documented, it would take an average of two days to find and then research a major proc that needed to be upgraded. I made the rule that if you touch the code, you must also document the code. After about a year, not only did the research required drop from 2 days to somewhere between 20 minutes and 2 hours, but the amount of code sent back by QA for faults went down from an average of two returns to nearly zero across the board.

    Jeff, I'm thinking about stealing this for part of my presentation. Do I have your permission to do so? 🙂

    Oh my... my apologies, Ray.  I missed this.  Sure, no problem.  You can also use the part where I say that if you strip away all the code, the comments should be simple but sufficient enough to create a functional flow chart from them.  I don't know why people don't "write the plan" into the code in the form of "comments first" and then simply fill in between the comments with the code to do what the comments say.  I guess that and writing a functional flow chart are arts lost in favor of programming off the cuff, which frequently results in failed code or failure to meet the given requirements.

    --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.
    "If you think its expensive to hire a professional to do the job, wait until you hire an amateur."--Red Adair
    "Change is inevitable... change for the better is not."
    When you put the right degree of spin on it, the number 3|8 is also a glyph that describes the nature of a DBAs job. 😉

    Helpful Links:
    How to post code problems
    Create a Tally Function (fnTally)

  • Ray K

    SSC-Dedicated

    Points: 31037

    Jeff Moden - Sunday, March 25, 2018 4:57 PM

    Ray K - Thursday, February 4, 2016 9:12 AM

    Jeff Moden (1/28/2016)


    I've found that many technologists that are in the business of writing code don't understand the extreme ROI of commenting code properly. In a previous company where no code was documented, it would take an average of two days to find and then research a major proc that needed to be upgraded. I made the rule that if you touch the code, you must also document the code. After about a year, not only did the research required drop from 2 days to somewhere between 20 minutes and 2 hours, but the amount of code sent back by QA for faults went down from an average of two returns to nearly zero across the board.

    Jeff, I'm thinking about stealing this for part of my presentation. Do I have your permission to do so? 🙂

    Oh my... my apologies, Ray.  I missed this.  Sure, no problem.  You can also use the part where I say that if you strip away all the code, the comments should be simple but sufficient enough to create a functional flow chart from them.  I don't know why people don't "write the plan" into the code in the form of "comments first" and then simply fill in between the comments with the code to do what the comments say.  I guess that and writing a functional flow chart are arts lost in favor of programming off the cuff, which frequently results in failed code or failure to meet the given requirements.

    LOL!  You're a little late, Jeff!  I've been using it in my presentation!

    Hope that's okay! 🙂

    +--------------------------------------------------------------------------------------+
    Check out my blog at https://pianorayk.wordpress.com/

Viewing 4 posts - 16 through 19 (of 19 total)

You must be logged in to reply to this topic. Login to reply