Tech Guides are Products too

Whenever I write a piece of code, configure an operating system, or install some software, I get stuck sometimes. When that happens, Google typically points me to two sources for help: StackOverflow answers and tutorials written in blogposts. The latter, I consider as : tech guides.

Putting aside StackOverflow, these well-meaning tutorials (aka tech guides) give me issues from time to time. The most common issue is that the code or instructions has errors. If I am lucky, another reader before me figures out the correct code and adds comment about the corrected version right at the end of the article. If not, then too bad for me.

Another common issue is when the guide is referencing a slightly older version of technology from the one I am using. And that makes their instructions not entirely useful for me. I then have to make a decision under uncertainty.

Should I downgrade my stack just to use their instructions

Do I keep searching to find another tutorial with instructions for the version I want to use?

What if this is the best instructions I can find? Should I spend a bit more time modifying the instructions to make it work for me?

Applying Product Thinking lens to tech guides

Running my own software agency is a great forcing function for learning what makes a good product. I like to apply some of this learning about good product to what makes an ideal tech guide. Therefore, this essay is my analysis of an ideal tech guide via the lens of product thinking.

I’ll start with studying the example of a good tech guide. Following that, I’ll build two lists. A list of undesirable attributes I see in most tech guides and a list of desirable attributes I want as a consumer of these information. Finally, I dig deeper into the user-centered perspective for more insights. That exercise produces a diagram listing more specific types of tech guide content and placing them in a 2×2 matrix.

So let’s get started with the first part by looking at a good example of a tech guide.

An example of a good tech guide

As stated in my What I’ll write about going forward, I aim to write more Guides. Given a career in software development, I suspect my first dozen or so guides will lean heavily in technology.

And a website producing good tech guides is the DigitalOcean community blog. Here’s an example about installing Docker in Ubuntu 18.04

Fig 1: Screenshot of a DigitalOcean tutorial. Notice the sticky left menu and the banner about versions.

As you scroll through the content, you’ll notice several things that the typical tutorial blogpost doesn’t have.

First, there’s a conscious design decision to present the content explicitly as a step-by-step guide. The steps naturally lend themselves well as the subheadings in the content.

Another great design decision is to have the subheadings as a sticky navigation menu on the left. So you can easily scroll up and down and you will know which step you are reading. This helps especially when the individual steps are verbose.

Next, notice there’s an editorial decision to have a single web page dedicated for installing a specific software on a specific version of a specific operating system.

I know that’s a mouthful, but look at the example above again. It’s about installing Docker on Ubuntu Linux v18.04.

And just to make it a little more user-friendly, they have that banner at the top to direct you to other versions of other operating systems in case the one you looking at is outdated.

Fig 2: The blue banner opens up a list of similar content for different OS

What I don’t like about most tech guides

Contrasting what DigitalOcean did right with the typical blogpost-style tech guides, I uncover 3 main gripes I have with most tech guides.

Buggy or incomplete instructions (when it happens)

Content referencing outdated versions (when it happens)

Laid out as essay rather than instructional piece (happens frequently)

As a reader of tech guides hunting high and low for an answer that works, it gets really annoying when I encounter 1) buggy instructions, or 2) outdated content.

In terms of points 2 and 3, DigitalOcean guides serve as an inspiration on how to overcome them. If the goal is to produce really good and authoritative tech guides, following DigitalOcean’s approach is not enough. I need to add to the approach by addressing point 1 regarding occasional buggy instructions.

The solution that comes to mind for the buggy instructions issue would be to write tests for the guide content. DigitalOcean guides don’t do that. To be fair, DigitalOcean’s guides are usually about installing software. And it’s hard to write tests for their kind of instructions. Code-related guides, on the other hand, are easier to write tests for. Code-related guides usually have topics like “How to search an element in a list in Python 3” for example.

Fig 3: An actual example of me commenting code corrections. Vitor has a great Django blog. Imagine how much better if such bugs get caught early by tests.

What I like to see in a tech guide

To sum up, my criteria of what an ideal tech guide looks like this:

Tests (be it unit, or integration) for the content

Clearly stating versions for primary technology in content

Same use case using same primary technology but different versions deserve different standalone guides

A UI/UX that makes more sense for step-by-step instructional content

I might be mistaken. But, I don’t think I have ever read any code-heavy tech guide that meets all 4 requirements in this list.

As I am writing this article, I also notice that I’m slowly differentiating the different types of tech content. Perhaps that might be a longer piece on its own in the future. In this section alone, I pointed out two types: code-related content and installing software content. I’m building up this list of different content types and go much deeper into it at the final part of this article.

Who’s the audience?

A common concept of product thinking is to think about who the users are and their needs. Then, design the product around that focus.

If I do that for tech guide, it’s a fair assumption that the audience will be technically aware developers. But, that oversimplifies the problem.

Different sub-groups in developer audience

At the start of my career, I was so green I often didn’t know which search terms to use to ask about my problem. It’s like when you look in a dictionary for the definition of a word and you don’t know the spelling. For a beginner developer trying to solve a business problem (see Note below) for a client, I was stuck in a similar way. I didn’t know which primary technology was suitable. Quite often, all I had to go with is the business formulation of the problem.

Note: When I use the term “business problem”, what I mean is the problem the non-technical stakeholder (usually your client) faces. Usually, it’s described in non-technical language. As a developer, you need to put together a technological solution for it. Almost certainly, it would be described in a broad, “big-picture” way.

The business formulation of a problem is usually how the client or a business analyst would express and frame with the problem. Now that I am a more experienced developer, I can use search terms more effectively. Even so, the business formulation of the issue is never far from my mind.

If I target beginner developers, they are likely to use search terms that are closer to the business formulation. For e.g., a possible question they will search for would be “How to implement a 2FA (two-factor authentication) for a web application?” If I target expert developers, they are likely to use search terms that are closer to the primary technology. Extending the 2FA example, their search query might be “How to implement a 2FA for a Django web application?” Thus, at the very least, there are two sub-groups of the developer audience. Each group has different educational needs.

Start with the business needs in mind

It’s getting messy raising the different questions about the user perspective. One way for me to make sense is to create a diagram tying together these different questions in my head. The hardest one to make sense are two dimensions in which I can place different tech content. How easily testable the instructions are and how much the content will appeal between beginner and expert developers.

Fig 4: The two dimensions are: how easy to write tests, and how relevant the content is between beginners and experts

When I place the common types of tech guide into this diagram, I get

Fig 5: The more code related, the easier to write tests for.

I want to focus your attention on two types of tech guide content. The code-centric content that addresses how to solve a business problem and the opinion-based content that addresses what language/framework to solve a business problem.

Fig 6: The two types of content that may be served better

My observation about these two content types is that most tech guides start with the technology in mind first in their writing. I want to highlight that the authors are not intentionally malicious when they write like that. Usually, they are written by expert developers deeply familiar with a particular technology. So they write in a tech-focused manner.

This doesn’t invalidate what they write. It’s also possible what they recommend is the best solution to the business problems the content address. The danger I want to highlight is that they are written by technologists naturally biased towards the technology perspective.

My thesis would be: what if, for those two content types, the tech guide start from the business problem perspective? Wouldn’t that be closer to the concerns of the potential readers? In other words, what if the market provides a business guide that happens to provide a technology solution, rather than a purely tech guide?

Going forward

I’m still stewing on this germ of a seed of an idea. I have not entirely made up my mind 100% on this topic about how best to write content. I may even rip up my list of desirable attributes or the diagram in some future article.

Nevertheless, most good ideas are not fully formed from the start. Given that I intend to reboot my blog in the coming new year, this seems as good an opportunity as any to experiment with new ideas on generating tech content.

Let me know your thoughts. Are you also thinking about writing guides or blog posts for fellow developers? What works for you? Tell me more below in the comments.