Over the years, writing about technology, I’ve produced many guides on how to do cool stuff (by my definition, at least) with your computer. But in all that time, I failed to devote any attention to how to approach those guides or any technical reference material. I assumed readers had the groundwork needed to use resources like mine.
As we all know, though, assumptions have consequences. Without the right foundation, even the most thorough guide can leave room for pesky variables to creep in. Covering every one of them is impossible, so given enough tinkerers over enough time, someone will hit a snag. All they have at this point is their cognitive toolset.
This made me realize how important it is to establish what a firm footing for technical projects looks like. I don’t know anyone who hasn’t breezed past correct procedures to attack a project, at least at first. This applies to me, too. Even now, I have to consciously check that my process is sound.
My goal is to ensure that we do things the right way from this point forward. I’ll teach you what steps to take, in what order, and how each step should be executed. The steps will be general enough to apply across programming languages, systems, and even entire disciplines.
The Journey of a Thousand Bytes Begins With a Single Step-by-Step
Let’s start by outlining the basic sequence. Afterward, we can revisit some of their considerations.
Step 1: Catalog all the pieces you will need. I say “pieces” because this could refer to literal parts for hardware-based projects or installed packages for software-based ones. You, the tinkerer, will know what pieces make the most sense.
Essentially, you’re taking inventory. When you open a box of furniture to be assembled, you check the contents before you start building, right? Same thing here. Unlike your DIY furniture, though, your project may include a manifest. There’s a good chance that the first step of this step is writing the manifest. Regardless, don’t move on until you are sure you’ve listed out every atomic unit to go from start to finish.
Step 2: Look up how all the pieces work. We’ll look at this closer in a bit since it’s trickier than it sounds. For now, just know that you will want to consult as much reputable documentation as needed to develop an articulable understanding of how each piece works and how each piece connects to all the others. If you haven’t already, definitely take notes.
Step 3: Determine the order in which the pieces need to be implemented or assembled. It’s possible that there are multiple viable sequences in which you can assemble the pieces. Great, but at this point, you should pick one and stick to it. Here, too, only you will know what you should pick, as it’s highly dependent on both your project and your style. Be sure to strictly observe hard prerequisites, though.
Step 4: Write a step-by-step instruction that outlines what you determined in Step 3. This is akin to pseudocode — and if you’re doing actual software development, it’s actual pseudocode. Pseudocode is exactly what it sounds like: it looks and acts like code but isn’t. Usually, it’s a blend of programming language syntax with natural language (e.g., English) semantics. It’s a halfway point between human and machine.
If you need ideas on where to start, you can see if someone else has written a guide for your project. You should still write your own, though! An online guide is no substitute for your own. That goes even for the ones I write. Consider pre-existing guides as a jumping-off point and nothing more.
When writing your guide, after each step in which you “do” something, you should follow it up with a test of what you just did. This adds an incremental workflow to your project. Don’t move on until the test succeeds. This makes your workflow iterative as well, repeating a step with piecemeal changes until everything you’ve built to that point is safely load-bearing for what will sit atop it.
Step 5: Prepare the environment for the instructions you wrote for yourself in Step 4. Think of this like the cooking show host who has all the ingredients measured, cut, and in separate bowls ready to pour in at the appointed time. This includes opening all the necessary manual pages and notebooks, installing the software you’ll be using (but not running or configuring it yet), and logging into any accounts or devices you need.
Step 6: Execute your instructions from Step 4. You know what to do here — you made certain of that in Step 4.
It’s Not the Size of the Step That Matters but How You Use It
There are a few points we need to keep in mind throughout the above process.
Audit the information you consult carefully for credibility. Most technical information you find on the web is wrong, and it’s because of the harsh reality of economics. Tech is lucrative because of high, rapidly increasing demand for tech professionals amid a low supply. To train the flood of aspiring tech professionals, tons of resources have been produced rapidly.
This is where market forces kick in. When demand outstrips supply, quality goes down, at least in the short term. Faster production with an increase in neither raw materials nor price produces lower quality. Most tech resources stayed free, and there are no more raw materials now than there were before, so training quality dropped.
But it gets worse. Not only is educational material written hurriedly and for an audience with a lower initial technical literacy, but the fresh tech workers trained on these materials become the new “experts.” They go on to write the next generation of educational resources and the vicious cycle of diminishing training quality continues.
Quality reference materials are out there, but they’re buried deeper and deeper. For this reason, you will have to identify trustworthy resources for yourself.
There are some checks you can run on a source to see if it meets reliable standards:
- Is it a for-profit organization? There’s a good chance it’s not too helpful. Many companies operating in the tech sphere are selling to an uninformed audience. When companies do have worthwhile tradecraft to share, they avoid giving it away for free — and even when they do, they may use it differently than you do.
- Is your source a nonprofit organization? It could be useful. Check the organization’s reputation and whether it is directly affiliated with the hardware or software you’re working with.
- Is your source organization primarily for training? If it’s also a for-profit company, be cautious. These companies’ priority is often job placement, not trainee quality. If it’s a nonprofit training group, it’s likely solid. Groups like that usually want to promote a technology or advance the field.
- Who authored your source? If the author works for a major tech company, for instance, but is offering the resource for free on their personal site, you can probably trust it. In a nutshell, always think about who is writing the advice you’re reading and why.
Never run code unless you are certain of what it does. This should really go without saying, but it’s important enough to say anyway. I’m pretty sure we all know this — but sometimes we’re too lazy to act on it. Don’t be lazy, or you might be sorry.
Write Good Pseudocode
Pseudocode quality correlates with project quality. The key to good pseudocode is getting as granular as possible. This is called “decomposition.”
To understand, let’s take a real-world example: if someone instructed you to cook a pot of spaghetti, you’d probably know what to do from past experience. When we think about it, however, this task is composed of about a dozen assumed steps. You need to get a packet of pasta, get a pot big enough for it, fill the pot with water…you get the idea.
When composing pseudocode, you must break your process down into these small, seemingly obvious steps. That’s because you’re doing something new and complex instead of habitual and simple. Once you decompose your process into its smallest parts, your granularity is just right.
There is a syntactic element that should be addressed, too.
Each one of your atomic steps should have its own line. Also, make your conditional and looping steps stand out. Typically, this is done using indentation.
For conditional statements, put the condition to be tested on the same level of indentation as the line above (unless it’s a loop or another conditional statement), and indent each step to be taken to satisfy that condition underneath it.
For looping statements, put the condition under which the loop iterates on the same level of indentation as the line above (unless it’s a conditional statement or another loop), and indent each step to be executed per iteration underneath it.
Go the Distance, Even When Your Feet Are Tired
It’s tempting to cut corners and take the it’s-probably-OK route. Don’t give in. A music teacher of mine had a saying in the form of a self-diagnostic: “How good would you be if you did everything you were supposed to do?” If you’re reading this article, you’ve put in the hours to know what the “right thing” is. So, if you’re not doing the right thing, it’s not out of ignorance — you’re choosing not to.
Why?
Yes, it takes more time upfront, but it saves more time later because everything is set up properly. Don’t choose to be less than you’re capable of being based on the whims of the moment.
Loading ...
