Taken from #68:
I think the installation instructions for lepidopter should be restructured to take into account the fact that there are two types of users of lepidopter (or maybe even 3):
A user of lepidopter that has gotten it via our partnership program. These from what I can tell are actually the majority of lepidopter users and are people that don't care how to burn the image to an SD card. This user is not technically savvy.
A user of lepidopter that wants to download the image and burn it onto their SD card. These are a minority of users that are quite technically savvy.
(if we include this as well) Power users or developers that want to contribute in some way to the project. Very technically savvy.
In light of this I think the guide should be divided into at least 2 sections.
User guide
How to burn an image
Inside the user guide there should be clear and simple explanations as to how to connect the raspberry pi to the power and internet (maybe even including screenshot). @andresazp showed me the document he created for VI and it looks great.
It should also cover information on how to initialise the pi (answering the informed consent) and check that measurements are being run, by visiting the web UI.
An outline of the User Guide could be:
Setting up the device (covering how to connect it to internet and power, putting in the SD card etc.)
First start (covering how to reach the pi over the network, using lepidopter or lepidopter.local) and answering the informed consent
Checking that everything works (checking that measurements are being run)
The How to burn an image can remain as the current section titled: "Downloading and verifying the Lepidopter Raspberry Pi image"
I would also try to make this guide overall much shorted and where possible point to external resources instead of having so much content in here (for example explaining the tests).
I am also thinking that maybe the whole part on burning the image could be tucked inside of another page entirely as it makes the whole guide much less user friendly.
Another comment is that the whole section "Lepidopter services" is far too technical and contains a bunch of information that will not be useful to most cases (why would the normal user care to know that there is a mDNS service for SSH?).
I would tuck this stuff as well inside of some advanced section and try to have a minimal guide that is easy for most users to follow.
The experience we had with real deployment of these is that even just explaining how to plug in a pi into a router and connecting to power can be challenging for some non technically savvy users and since this guide is addressed to them we should take that into account.