Abstract: Tech Writing for Techies

Question

Abstract: Tech Writing for Techies

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

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

Ray K SSC-Dedicated Points: 31166 More actions · Answer 1

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: 31166 More actions · Answer 2

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: 1004415 More actions · Answer 3

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.

Change is inevitable... Change for the better is not.

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

Ray K SSC-Dedicated Points: 31166 More actions · Answer 4

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/