Previous Page

nihilist@mainpc - 2024-08-19

How to write good Tutorials

Because after all, how can you expect people to write good tutorials without showing them how to write tutorials in the first place ?

Why?

Context: Suppose you are discovering OPSEC, Technology and all their abstract concepts, you are amazed at what you are finding, and you are now feeling very enthusiastic about sharing it to other people, but you don't know how to do it.

Situation: You go into that SimpleX chatroom you find that random dude called nihilist and you start to explain into great detail how you managed to implement QubesOS with that whonix Xen VM, and that he should also force a VPN through the SOCKS Tor proxy and you proclaim that this is the ultimate setup, and everyone should implement it. But before you can finish your ramblings the guy already ran away scared, he thought you were threatening him and his family.

Are you OK with how badly you just communicated ? Are you fine with shouting your message out there without firmly grabbing anyone's attention?

What?

There exists a process, that this guy nihilist is using all the time on his OPSEC Blog, which is in 3 simple steps:

1. Why ? Why the hell should others care about your message in the first place ? In which context ?

2. What ? If they care, What are the tools at their disposal to solve that problem ?

3. How ? How, step by step, can they use those tools to solve the problem ?

Don't mix up the order. First the Why, then the What, then the How.

How ?

Now that you are aware that there is a way to write good quality tutorials, let's look at how to write them, step by step.

First, ALWAYS start with the WHY, why the hell should all those mortals even care about your message. To do that, you need to tell them a story that highlights a problem. Most people may not even aware that there is a problem in the first place, so you must tell them, to make them aware of it.

So you first contextualize your story, then you explain the situation, and then you ask them if they are ok with it.

Context: In your house, in your bedroom, if there are windows to look outside
Situation: the annoying neighbor always stops by to look at what you're doing in your bedroom
Are you ok with this situation ?

Now that the problem has been highlighted, you can tell them WHAT their options are:

You have a few options to prevent your annoying neighbor from seeing what you're doing in your bedroom:
1) get rid of all windows and have a house with only walls : expensive
2) install curtains on your windows : inexpensive

Now that you have listed their options, you can showcase HOW to implement an option you choose

WARNING: people don't want to read your wall of text, one way to make it fancy is to add graphs to help your readers visualize the idea you are trying to convey:

Let's showcase how to install curtains, as it's the easiest and cheapest solution to prevent outsiders from seeing what you're doing in your bedroom.

1) buy it, 
2) then you attach it above your windows, using screws and screwing it into the wall, (warning, if you're living in an apartment, ask for your landlord's permission!)
3) then you can move the curtain to prevent outsiders from peeking in

Do not skip steps, otherwise your readers will get lost. and explain each step in great detail, that way there is no ambiguity. To reduce the ambiguity, show what you're seeing when you are doing the steps yourself (take pictures, copy paste from your terminal, etc)

If there are any important points that your readers need to be aware of, make sure you tell them, and how they can proceed in that second situation too. It is important to make sure they understand the why along each step they do.

And finally, congratulate your users as you conclude on what they managed to accomplish:

Congratulations, you just managed to gain privacy at your own house / apartment ! You just reached OPSEC level 1!

Congratulations, you just managed to write a good tutorial, you highlighted why your users should care about your message, and if they care you just told them how they can solve the problem ! You now have the proper methodology to write top quality tutorials, and to communicate in a clear, and concise manner.