January 27, 2016 at 8:34 am
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/
January 28, 2016 at 5:12 am
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
Author of:
SQL Server Execution Plans
SQL Server Query Performance Tuning
January 28, 2016 at 7:32 am
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/
January 28, 2016 at 8:33 pm
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
Change is inevitable... Change for the better is not.
January 29, 2016 at 6:19 am
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/
January 29, 2016 at 9:51 am
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
Author of:
SQL Server Execution Plans
SQL Server Query Performance Tuning
January 29, 2016 at 1:45 pm
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/
January 30, 2016 at 4:32 am
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
Author of:
SQL Server Execution Plans
SQL Server Query Performance Tuning
January 30, 2016 at 6:42 am
Ray, that sounds like a great presentation. Do you present in Albany, NY only or to you get around in the northeast and midwest?
January 31, 2016 at 10:52 am
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/
January 31, 2016 at 11:08 am
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/
February 1, 2016 at 6:27 am
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
Author of:
SQL Server Execution Plans
SQL Server Query Performance Tuning
February 1, 2016 at 6:33 am
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
February 1, 2016 at 7:13 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.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
February 4, 2016 at 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? 🙂
+--------------------------------------------------------------------------------------+
Check out my blog at https://pianorayk.wordpress.com/
Viewing 15 posts - 1 through 15 (of 18 total)
You must be logged in to reply to this topic. Login to reply