Wiki¶

Introduction¶

The main Replicant documentation is on the Replicant wiki and directly on the https://www.replicant.us/ website (like for the freedom-privacy-security-issues) 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.

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

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 respect users freedom with the documentation content as well.

• 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.

See also¶

Bridging the Gap between Legacy Docs and Modular Content¶

This is a FOSDEM 2017 talk about "monolythic and comprehensive documentation" (Example ) which is called "Legacy" in that talk, VS "modular, non comprehensive and use case targetted documentation" (Example) which is called "Modular" in this talk.

• Question @24min56seconds" "So you are asking how to organize the assemblies [documentation on how to do a specific thing, example: install Replicant] that we are going to end up with [...] and maintain them". Answer: [...] You have to apply a lot of planning for, [...].