This is a great reminder!
First, read what Jason Cannon <support@linuxtrainingacademy.com> wrote in his email with the subject "The biggest mistake shell scripters make." to whom I am giving every speck of credit to for his words (of course!) Then, read what I wrote back to him. Here's his email:
Hello,
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!)
The offer to review a shell script is almost irresistible to me, so I'll say "Sure, I'll look at it."
Reviewing scripts gives me the chance to see many common mistakes. And the number one biggest mistake of all is:
Not defining exactly what the shell script is supposed to do!
What is supposed to happen when I run this shell script?
Why does this script exist?
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. Again, this is a very common mistake... a mistake I used to make when I first started scripting, too. This is coming from a place of caring. I *want* people to write awesome shell scripts and I *love* helping them do so!
So, here's my first piece of advice to any (new) 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 want to learn all the best scripting "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.
All the best,
Jason
P.S. Want to vastly improve your shell scripting skills quickly? Want help from me personally? Then click here.
Unsubscribe | 400 Locust Street, Suite 400. Des Moines, IA 50309
And this is what I wrote back to him:
I don't know squat about Linux. I read your emails because I want to learn more.
That said, your email below is spot-on. I see an easy transition from "Define the requirements for your Linux shell script" to "Define the requirements for your MS Word macros."
For example, I have a MS Word macro that will set the Subject and Title file properties to the file name. If the MS Word file is called "Access-UIHC-Network-from-Home.docx", the Subject and Title fields are both set to " Access-UIHC-Network-from-Home" – the macro has saved me a lot of manual work over the last few years. Last week, though, there arose a new requirement. The Access-UIHC-Network-from-Home.docx file actually has a 5 character Knowledge Article ID and when I looked in a folder of 60ish Word files, there was no easy way to identify that Access-UIHC-Network-from-Home.docx is actually the content for KA ID 10455. So, I renamed those 60ish Word files to have the KA ID as the prefix, meaning Access-UIHC-Network-from-Home.docx is now 10455- Access-UIHC-Network-from-Home.docx. However, the way I have the Word files set up is that all Heading 2s in the Word file has the "Subject" field as a prefix, which now means I have something like the following:
Note: the following is off the top of my head and not reflective of an actual document
<begin Document>
<h1>10455-Access-UIHC-Network-from-Home </h1>
<h2>10455-Access-UIHC-Network-from-Home – Overview</h2>
If you are working remotely, you can access the UIHC network from your laptop as if you were on campus.
<h2>10455-Access-UIHC-Network-from-Home – Prerequisites</h2>
To set up access, verify that you meet the following requirements.
Requirement 1
Requirement 2
Requirement 3
<h2>10455-Access-UIHC-Network-from-Home – Set Up Firewall</h2>
You must set up your firewall to allow access to the network. To do this, follow these steps:
1.Step 1
2.Step 2
3.Step 3
<h2>10455-Access-UIHC-Network-from-Home – Set Up Device</h2>
You must set up your device with required anti-virus software. To do this, follow these steps:
1.Step 1
2.Step 2
3.Step 3
<end document>
If the document has a TOC, the KA ID is repeated in each line of the TOC. I think it looks like a mess.
So now, how do I fix it? Well, I probably need to figure out how to truncate the first 6 characters of the file name and set that value to the Subject field.
My point is that I now have a new requirement and a specific purpose for creating it and your email reminded me it's crucial for me to take the time to figure out what I need before I actually try to solve the problem! Thanks for the reminder!
