Abstract: Tech Writing for Techies

  • Ray K

    SSC-Dedicated

    Points: 31037

    Wanted to run a possible presentation idea past everyone, and see what people think.

    "Tech Writing for Techies: A Primer"

    Technologists, in general, have a reputation for not being very good writers. However, documentation is one of the most overlooked -- yet most critical -- business functions. This presentation provides an overview of what technical writing is all about, how technologists can contribute to better documentation, and how it can improve your business.

    The idea for this pretty much spun off from a presentation I've been doing for SQL Saturday about how to talk to non-technical people (I include a section on documentation, and was thinking about expanding on it; hence, my presentation idea).

    What do people think? Would this make for a viable topic? Anything that I should/shouldn't include?

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

  • Grant Fritchey

    SSC Guru

    Points: 395399

    Great topic. I'd add one more sentence to the abstract. It feels short. I'd add two or three specific techniques that you're going to teach so that people know what they're taking back to the office.

    ----------------------------------------------------
    The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood...
    Theodore Roosevelt

    The Scary DBA
    Author of: SQL Server 2017 Query Performance Tuning, 5th Edition and SQL Server Execution Plans, 3rd Edition
    Product Evangelist for Red Gate Software

  • Ray K

    SSC-Dedicated

    Points: 31037

    Grant Fritchey (1/28/2016)


    Great topic. I'd add one more sentence to the abstract. It feels short. I'd add two or three specific techniques that you're going to teach so that people know what they're taking back to the office.

    Okay. Let me chew on it and see what I can do with it. I've already submitted it for a couple of SQL Saturdays (yes, I'll make sure I edit my abstracts!), so I have some incentive to work on this.

    Thanks for the feedback as always, Grant!

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

  • Jeff Moden

    SSC Guru

    Points: 994269

    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.

    And to be sure, comments like "Update the Customer table" are totally useless. I tell people that if you remove all of the code, the comments that remain should be sufficient to allow you to create a functional flow chart.

    --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

    I agree completely; in fact, I've written that down as one of my notes for the presentation. Even something as simple as code comments counts as documentation.

    I had professors in college who used to dock points if we didn't comment our code!

    I have some ideas as to where to take this presentation. Let me see what I can do with it. Thanks for the feedback!

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

  • Grant Fritchey

    SSC Guru

    Points: 395399

    Sounds great. Can't wait to sit through it.

    ----------------------------------------------------
    The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood...
    Theodore Roosevelt

    The Scary DBA
    Author of: SQL Server 2017 Query Performance Tuning, 5th Edition and SQL Server Execution Plans, 3rd Edition
    Product Evangelist for Red Gate Software

  • Ray K

    SSC-Dedicated

    Points: 31037

    Grant Fritchey (1/28/2016)


    Great topic. I'd add one more sentence to the abstract. It feels short. I'd add two or three specific techniques that you're going to teach so that people know what they're taking back to the office.

    What you think of this?

    "Some ideas we will discuss include: why documentation is important, why technologists tend to be averse to documentation, what you could do to improve your writing, and what kinds of documentation exist."

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

  • Grant Fritchey

    SSC Guru

    Points: 395399

    Ray K (1/29/2016)


    Grant Fritchey (1/28/2016)


    Great topic. I'd add one more sentence to the abstract. It feels short. I'd add two or three specific techniques that you're going to teach so that people know what they're taking back to the office.

    What you think of this?

    "Some ideas we will discuss include: why documentation is important, why technologists tend to be averse to documentation, what you could do to improve your writing, and what kinds of documentation exist."

    Good. I definitely like it when added to what you have above. The first two points are a little bit repetitive of the rest of the abstract. Can you replace the averse thing with something else?

    ----------------------------------------------------
    The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood...
    Theodore Roosevelt

    The Scary DBA
    Author of: SQL Server 2017 Query Performance Tuning, 5th Edition and SQL Server Execution Plans, 3rd Edition
    Product Evangelist for Red Gate Software

  • Ed Wagner

    SSC Guru

    Points: 286957

    Ray, that sounds like a great presentation. Do you present in Albany, NY only or to you get around in the northeast and midwest?

  • Ray K

    SSC-Dedicated

    Points: 31037

    Grant Fritchey (1/30/2016)


    Ray K (1/29/2016)


    Grant Fritchey (1/28/2016)


    Great topic. I'd add one more sentence to the abstract. It feels short. I'd add two or three specific techniques that you're going to teach so that people know what they're taking back to the office.

    What you think of this?

    "Some ideas we will discuss include: why documentation is important, why technologists tend to be averse to documentation, what you could do to improve your writing, and what kinds of documentation exist."

    Good. I definitely like it when added to what you have above. The first two points are a little bit repetitive of the rest of the abstract. Can you replace the averse thing with something else?

    Hmmm, let me ponder a little more!

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

  • Ray K

    SSC-Dedicated

    Points: 31037

    Ed Wagner (1/30/2016)


    Ray, that sounds like a great presentation. Do you present in Albany, NY only or to you get around in the northeast and midwest?

    I signed up to present in Ottawa, Rochester, Maine, and of course, my hometown SQL Saturday in Albany.

    For now, I've been applying mainly to SQL Saturdays within driving distance, but if my wife will let me spend the money on a plane ticket, maybe I can venture outside the Northeastern US at some point! 🙂

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

  • Grant Fritchey

    SSC Guru

    Points: 395399

    Well, just remember, I'm just some guy and my opinion isn't worth much more than others. If you're happy with it, use it. Plus, I keep getting rejected on PD sessions.

    ----------------------------------------------------
    The credit belongs to the man who is actually in the arena, whose face is marred by dust and sweat and blood...
    Theodore Roosevelt

    The Scary DBA
    Author of: SQL Server 2017 Query Performance Tuning, 5th Edition and SQL Server Execution Plans, 3rd Edition
    Product Evangelist for Red Gate Software

  • Gail Shaw

    SSC Guru

    Points: 1004424

    Ray K (1/31/2016)


    For now, I've been applying mainly to SQL Saturdays within driving distance, but if my wife will let me spend the money on a plane ticket, maybe I can venture outside the Northeastern US at some point! 🙂

    I hear Iceland is nice in June. http://www.sqlsaturday.com/516/eventhome.aspx

    Gail Shaw
    Microsoft Certified Master: SQL Server, MVP, M.Sc (Comp Sci)
    SQL In The Wild: Discussions on DB performance with occasional diversions into recoverability

    We walk in the dark places no others will enter
    We stand on the bridge and no one may pass
  • Eric M Russell

    SSC Guru

    Points: 124991

    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.

    And to be sure, comments like "Update the Customer table" are totally useless. I tell people that if you remove all of the code, the comments that remain should be sufficient to allow you to create a functional flow chart.

    Regarding commenting of stored procedures and views, I'll paste into the header comments the SharePoint URL where the original requirements and design documents are located. Also required are a one line comment consisting of the date / CO number / developer's name and brief description for each subsequent modification. Often times I'll even throw in a unit test block, basically a handful of EXEC procedure calls with sample input parameters that are known to work in development for various scenarios. Armed with all that, even a new developer coming in off the street can get ramped up fairly quickly.

    "Do not seek to follow in the footsteps of the wise. Instead, seek what they sought." - Matsuo Basho

  • Ray K

    SSC-Dedicated

    Points: 31037

    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? 🙂

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

Viewing 15 posts - 1 through 15 (of 19 total)

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