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.

h2. See also

h3. "Bridging the Gap between Legacy Docs and Modular Content":https://archive.fosdem.org/2017/schedule/event/legacy_docs/ 

This is a FOSDEM 2017 talk about "monolythic and comprehensive documentation" ("Example":https://guix.gnu.org/manual/en/guix.html ) which is called "Legacy" in that talk, VS "modular, non comprehensive and use case targetted documentation" ("Example":https://redmine.replicant.us/projects/replicant/wiki/Installation) which is called "Modular" in this talk. 

h4. Interesting parts

h5. 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, [...].

h5. Question @ 39min27seconds

[...] I think that something that is hard with the modular approach is to be able to oversee all the modules and how they can be reused, so if you have one user story, I agree that it's much easier to change it somewhere?/in some way?, but there is a new role which is assembling [...] all thoses modules and having an idea of what should be specific, what should be generic, and I think that's [...] a role that needs to have an overview of even more even wider overview than in the legacy documentation", do you have something to say about that?"

Solutions:

* Mind mapping is used to keep track of the documentation status

* Hierarchical structure

* Metadata (tags, etc) used to understand what we already have

** It could be implemented as cathegories in mediawiki in Replicant