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


Abstract: Tech Writing for Techies


Abstract: Tech Writing for Techies

Author
Message
Ray K
Ray K
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: 26095 Visits: 5317
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
Grant Fritchey
SSC Guru
SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)

Group: General Forum Members
Points: 350492 Visits: 34244
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
Ray K
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: 26095 Visits: 5317
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
Jeff Moden
SSC Guru
SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)SSC Guru (858K reputation)

Group: General Forum Members
Points: 858315 Visits: 47068
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

Helpful Links:
How to post code problems
How to post performance problems
Forum FAQs
Ray K
Ray K
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: 26095 Visits: 5317
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
Grant Fritchey
SSC Guru
SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)

Group: General Forum Members
Points: 350492 Visits: 34244
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
Ray K
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: 26095 Visits: 5317
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
Grant Fritchey
SSC Guru
SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)SSC Guru (350K reputation)

Group: General Forum Members
Points: 350492 Visits: 34244
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
Ed Wagner
SSC Guru
SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)SSC Guru (259K reputation)

Group: General Forum Members
Points: 259792 Visits: 12217
Ray, that sounds like a great presentation. Do you present in Albany, NY only or to you get around in the northeast and midwest?


Tally Tables - Performance Personified
String Splitting with True Performance
Best practices on how to ask questions
Ray K
Ray K
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: 26095 Visits: 5317
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/
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