Replicant » Documentation

h1. Wiki

h2. Introduction

The main Replicant documentation is on the "Replicant wiki":https://redmine.replicant.us/projects/replicant/wiki and directly on the https://www.replicant.us/ website (like for the "freedom-privacy-security-issues":https://www.replicant.us/freedom-privacy-security-issues.php) page.

This sub-project and wiki (https://redmine.replicant.us/projects/documentation/wiki) instead contain information on how to best contribute to the Replicant project documentation, how to manage the huge amount of documentation, etc.

h2. Guidelines for writing documentation

h3. "Flashing", "to flash", etc.

In the Replicant documentation, you might be tempted to use wording like: <pre>You need to flash the recovery with the following command</pre>. 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 install 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.

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

It's a good idea to also respect users freedom with the documentation content as well. 

For instance, 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 type this command@. This enables users to understand what they are doing, and if necessary challenge and/or improve the documentation. 

* 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 wish. If users are very technical and don't want to follow the specific instructions for a reason or another, if we already give some background information (for instance we can tell them that we need to install a recovery image), very technical users might find another way to do it, which is not necessarily documented (for instance they might want to use fastboot instead of heimdall to install a recovery image on some devices because on their computer Heimdall doesn't work). For instance, this can be done by using @For instance@.

* If something needs to be followed by the letter, like heimdall commands, we could then tell them exactly why, for instance @If you use the wrong command it could break the device@. In that case users that know what they are doing will most probably understand the risk and if they are using fastboot instead they will most likely understand that it also applies to fastboot as well and why.