In my brain, I can apply the advice from Jason Cannon to my daily work as a technical writer. Another aspect of "START with the END in mind!" is "Who is your audience?" as well as "What is your purpose for the communication - words, images, video, anything else - and what is the most efficient manner to communicate the information you need to communicate to that audience?"
Editor's Note: That was very clumsy, but several attempts at rewriting it have failed. Sigh.
From: Jason Cannon
Sent: Tuesday, August 18, 2020 5:49 AM
Subject: Linux shell scripting tips
Hi there,
From time to time one of my students will ask me to take a look at one of their shell scripts that they are having trouble with.
If you know anything about me at all, you know that I love three things. Linux, troubleshooting, and shell scripting. (Make that four things... teaching my love of Linux, troubleshooting and shell scripting!)
It's almost irresistible to me so, so I'll say "Sure, I'll look at your script."
Invariably they'll send over a 100+ line shell script, riddled with syntax errors, inexplicable pieces of code, meaningless variable names and.... worst of all:
They don't tell me what the shell script is supposed to do!
Why does this script exist?
What will it accomplish upon a successful run?
Can I at least get a simple comment at the top of the script justifying its existence?!? (Um, no.)
By the way, I'm not judging or blaming. We all start at the beginning. ;-) This is coming from a place of caring. I *want* people to write awesome shell scripts and I *love* helping them do it!
So, here's my first piece of advice to any shell scripter:
START with the END in mind!
Why?
Well... sometimes people make assumptions about HOW to accomplish their larger goal. You may think you need to do A, B, C, D, E, F, G, and so on to get to Z, but in reality there may be a shortcut that takes you straight from A TO Z. (Shortcuts like bash builtins, predefined shell variables, Linux commands that you didn't even know existed, etc.)
It's the age-old case of not being able to see the forest for the trees and getting lost in the weeds. :-)
You could easily end up with this:
When all you needed was this:
(Shameless plug: If you need help with learning the "shortcuts," check out my latest project-based shell scripting class here.)
Another trap you can fall into is biting off more than you can chew. Once you have a goal in mind for your script, keep it focused on the essentials.
- What MUST this script do?
- If this script could only do one thing, what would that be?
- What will get me 90% of the way to my goal with the least amount of effort?
Start there. Implement that first, then circle back around to the "nice-to-haves" or bigger goals for your script.
It's way easier to light a room in your house than it is to illuminate the entire neighborhood.
Now you know where to start. In the next email, you'll learn how to write a shell script.
Best wishes,
Jason
No comments:
Post a Comment