Writing about technology over the years, I have produced many guides on how to do cool things (by my definition, at least) with your computer. But in all that time, I didn’t pay attention to how to approach those guides, or any technical reference material, really. I assumed that readers had the necessary groundwork to make use of resources like mine.
However, as we all know, assumptions have consequences. Without the proper foundation, even the most comprehensive guide can leave room for pesky variables to leak out. Covering each one of them is impossible, so if you give it enough touch-ups for long enough, someone will run into a snag. All they have at this point is their cognitive toolkit.
This made me realize how important it is to establish a firm foundation for technical projects. I don’t know of anyone who hasn’t gone through the correct procedures for attacking a project, at least initially. This also applies to me. Even now, I have to consciously check that my process is correct.
My goal here is to make sure that from now on we do things the right way. I’m going to show you what steps to follow, 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 thousand-byte journey begins with a single step-by-step
Let’s start by outlining the basic sequence. Then we can review some of your considerations.
Step 1: List all the parts you will need. I say “parts” because this could refer to literal parts for hardware-based projects or installed packages for software-based projects. You, the handyman, will know which pieces make the most sense.
Basically, you are taking inventory. When you open a box of furniture to assemble, you check the contents before you start building, right? The same here. However, unlike your DIY furniture, your project may include a manifest. The first step in this step is most likely to be writing the manifest. Regardless, do not continue until you are sure you have listed all the atomic units to go from start to finish.
Step 2: See how all the pieces work. We’ll take a closer look at this in a moment, as it’s more complicated than it sounds. For now, just know that you’ll want to refer to as much reliable documentation as is necessary to develop an articulated understanding of how each part works and how each part connects to all the others. If you haven’t already, definitely take notes.
Step 3: Determine the order in which the parts should be deployed or assembled. There may be multiple viable sequences in which you can assemble the pieces. Great, but at this point you have to pick one and stick with it. Here, too, only you will know what to choose as it largely depends on both your project and your style. However, be sure to strictly observe the strict prerequisites.
Step 4: Write a step-by-step instruction that describes what you determined in Step 3. This is similar to pseudo code, and if you are developing real software, it is real pseudo code. Pseudocode is exactly what it sounds like – it looks and acts like code, but it isn’t. Usually it is a mixture of programming language syntax with natural language semantics (for example, English). It is an intermediate point between humans and machines.
If you need ideas on where to start, you can see if someone else has written a guide for your project. However, you should still write yours! An online guide is not a substitute for yours. That is true even for those who write. Consider the pre-existing guides as a starting point and nothing more.
When writing your guide, after each step you “do” something, you should follow up with a test of what you just did. This adds an incremental workflow to your project. Do not continue until the test is successful. This also makes your workflow iterative, repeating a step with partial changes until everything you’ve built up to that point safely supports the load for what will be placed on top.
Step 5: Prepare the environment for the instructions you wrote yourself in Step 4. Think of this as a cooking show host who has all the ingredients measured, cut up, and in separate bowls ready to serve at the agreed time. This includes opening all the necessary manual pages and notebooks, installing the software that you will use (but not running or configuring it yet), and logging into whatever account or device you need.
Step 6: Run your instructions from Step 4. You know what to do here; made sure of that in step 4.
It is not the size of the step that matters, but how you use it
There are some points that we must keep in mind throughout the previous process.
Audit the information you consult carefully to verify its credibility. Most of the technical information you find on the web is incorrect and due to the harsh reality of the economy. The technology is lucrative due to the high and rapid demand for technology professionals amid tight supply. To train the flood of aspiring tech professionals, tons of resources have been quickly produced.
This is where market forces come into play. When demand exceeds supply, quality declines, at least in the short term. Faster production without an increase in raw materials or price produces a lower quality. Most of the technology resources were kept free and now there are no more raw materials than before, so the quality of the training was reduced.
But it gets worse. Not only are educational materials written in a hurry and for an audience with lower initial technical knowledge, but new technology workers trained in these materials become the new “experts.” They continue to write the next generation of educational resources and the vicious cycle of decreasing quality of training continues.
There are quality reference materials, but they are increasingly buried. For this reason, you will have to identify reliable resources for yourself.
There are a few checks you can run on a font to see if it meets trusted standards:
- Is it a for-profit organization? It is most likely not very useful. Many companies operating in the tech sphere are selling to an uninformed audience. When companies have commercial material worth sharing, they avoid giving it away and even when they do have it, they may use it differently from you.
- Is your source a non-profit organization? It could be useful. Check the reputation of the organization and if it is directly affiliated with the hardware or software you are working with.
- Is your home organization primarily for training? If you are also a for-profit company, be careful. The priority of these companies is usually job placement, not the quality of the apprentices. If it’s a nonprofit training group, it’s probably solid. Groups like that generally want to promote a technology or advance in the field.
- Who was the author of your font? If the author works for a major tech company, for example, but offers the resource for free on his personal site, you can probably trust him. Simply put, always think about who writes the advice you are reading and why.
Never run code unless you are sure what you are doing. This should go without saying, but it’s important enough to say anyway. I’m pretty sure we all know this, but sometimes we are too lazy to act on it. Don’t be lazy, or you will regret it.
Write a good pseudocode
The quality of the pseudocode is correlated with the quality of the project. The key to good pseudocode is to be as granular as possible. This is called “decomposition.”
To understand this, let’s take a real-world example: If someone were to instruct you to cook a pot of spaghetti, you would probably know what to do from past experiences. However, when we think about it, this task is made up of a dozen steps taken. You need to get a packet of pasta, get a pot big enough, fill the pot with water… you get the idea.
When writing pseudocode, you need to break your process down into these seemingly obvious little steps. That’s because you are doing something new and complex instead of the usual and simple. Once you break down your process into its smallest parts, your granularity is just right.
There is a syntactic element that should also be addressed.
Each of your atomic steps must have its own line. Plus, make your looping and conditional steps stand out. Typically this is done by indentation.
For conditional statements, put the condition to be tested at the same level of indentation as the previous line (unless it is a loop or other conditional statement), and indent each step that will be taken to satisfy that condition below she.
For loop statements, put the condition under which the loop iterates at the same level of indentation as the previous line (unless it is a conditional statement or another loop), and it indents each step to be iterated below it .
Go the distance, even when your feet are tired
It is tempting to cut corners and take the route that is probably okay. Do not give up. One of my music teachers had a saying in the form of self-diagnosis: “How good would you be if you did everything you are supposed to do?” If you are reading this article, you have spent hours learning what is “right”. So if you are not doing the right thing, it is not out of ignorance, you are choosing not to do it.
Yes, it takes more time up front, but saves more time afterwards because everything is set up correctly. Do not choose to be less than what you are capable of basing on the whims of the moment.