Wiki¶

Guidelines for writing documentation¶

"Flashing", "to flash", etc.¶

In the Replicant documentation, you might be tempted to use wording like:

You need to flash the recovery with the following command

, however many people don't know what that verb means. As many more people know what the 'install' word means, it's better to use that instead.

So You need to flash the recover with the following command becomes You need to install the recovery with the following command.

In addition, many devices use eMMC which are exposed as block devices, just like hard disks, so 'flashing' becomes more confusing as the line is blured between MTD devices that exposes RAW flash and those who don't.

There is more than one way to do it and users freedom.¶

It's a good idea to also give user freedom while following the documentation. To do that:

We can explain what we are doing and why we need to do it. For instance instead of using Type this command, you can use To install the recovery, you can this command
It's a good idea to tell users that there might be more than one way to do it, but that we are giving a specific example that they can follow. If they are very technical and don't want to follow the specific instructions for a reason or another, if we already give some background installation (for instance that we need to install the recovery), very technical users might find another way to do it (for instance use fastboot instead of heimdall on some devices).