Restructure /e/ User Documentation Pages
Summary
The current /e/ user documentation consists of over 750 device-specific pages, many of which have never been reviewed, and some of which contain serious errors.
I propose a restructuring of the documentation into a single 'User Manual' document, implemented as a gitlab wiki, which would
- reduce the number of pages that need checking and maintaining down to less than 50
- improve the quality of the user documentation, by removing / correcting many of the errors at a relatively low cost.
Current structure
Around 250 devices with at least 3 pages for each device
- Info page e.g. https://doc.e.foundation/devices/z3c
- Install page e.g. https://doc.e.foundation/devices/z3c/install
- Upgrade page e.g. https://doc.e.foundation/devices/z3c/upgrade
- plus ~90 posts in the 'Documentation Suggestions' and other forum pages, with at least one reply, containing information (sometimes original, sometimes duplicating official pages, sometime right, sometimes wrong)
So over 800 device-specific pages, many (most) of which
- have been produced from templates (which may or may not have ever been reviewed, and which may or may not have changed since they were used by /e/ to create their own pages)
- have never been reviewed
- contain errors and broken links, either imported with the templates, or introduced by /e/
I propose a new structure, outlined below, that would reduce this to around 270 pages
250 device-specific documentation pages - one page per device - to be (eventually) reviewed - possibly be /e/ community users or volunteers - and corrected and maintained by /e/ staff (existing developers, or new specialist staff)- 10-15 'HOW TO' pages, describing how to complete different tasks associated with installing, updating, and upgrading /e/OS
- 15-20 manufacturer-specific pages, one for each manufacturer. These pages would contain
- Device-specific sections for each device, split into official and unofficial supported devices, containing
- links for downloading recovery, easy installer, /e/OS and stock firmware images
- details of any device-specific variations on the generic "HOW TO" pages
- list of supported models / model numbers
- Information on manufacturer-specific tools, including trusted download links, and links to upstream documentation.
- Device-specific sections for each device, split into official and unofficial supported devices, containing
(There are also 250 ROM Download pages e.g. https://images.ecloud.global/dev/z3c/ which are maintained and updated semi-automatically by the /e/ build team. I do not propose to change those.)
Proposed New Structure
HOW TO pages
Each page contains
- Generic instructions for each task
- Manufacturer-specific variations / exceptions (where specific manufacturers do things differently to the generic instructions, .e.g links to manufaturers' 'Unlock bootloader' instructions e.g. https://developer.sony.com/develop/open-devices/get-started/unlock-bootloader/)
- Download links for any tools needed for that task: generic (e.g.
fastboot
,adb
) or manufacturer specific (e.g.Heimdal
&Odin
for Samsung,flashtool
andxperifirm
for Sony) - Computer OS-specific instructions: Windows, Linux, MacOS
- A clear indication of the completeness, and 'Validation status' of the page (see 'Validation' below), so that users know how much they can rely on the accuracy of the information given in the page
- A link allowing users to report errors and/or ask for clarification (easily, without needing to have a gitlab login)
Each main bullet point in the following list is a separate page: numbered items, and further bullet points, are sections and subsections within the page:
-
Introduction
- Explain the structure
- Index of 'HOW TO' pages
- Index of 'Device-specific' pages
-
Install needed tools
- platform tools -
adb
,fastboot
- Manufacturer-specific tools
- Samsung -
Heimdal
,Odin
, - Sony -
xperifirm
,flashtool
- Motorola - ??
- ??
- Samsung -
- platform tools -
-
Activate
adb
debugging -
Unlock the bootloader
- Check whether it is allowed
- Find and record device IMEI
- Get unlock code
- unlock with
fastboot
- unlock with
adb
-
Install and boot into recovery
-
First install
- Download ROM
- Flash with
adb sideload
- Install from recovery
- TWRP
- /e/ Recovery
- Install with
Easy Installer
-
Backup / Restore
- TWRP
- /e/ Recovery
- SeedVault
- 'Android Backup and Restore Tools' project
-
Update
- Dirty flash
- OTA
- with
adb
- from recovery
- with
Easy Installer
- Backup / Clean Flash / Restore
This page may refer to, but not duplicate sections of the 'First install' page
- Dirty flash
-
Upgrade to higher Android version
-
Flash Stock Android
- Same Android version
- Higher / newer Android Version
- Lower / older Android Version
-
/e/OS GSIs
-
Build /e/OS
Device-specific pages
Each page contains
- For each task
- link to the HOW TO pages for that task, mentioning any manufaturer-specific variations
- Device-specific variations / exceptions (where specific devices do things differently to the generic and/or manufacturer-specific instructions)
- Links to
- ROM download pages for the device
- Recovery download pages for the device
- TWRP
- /e/ Recovery
- Others
- Currently open bugs for the device
- Device specifications and images
- Acknowledgement of upstream developers
Who will use this new feature?
/e/ Users
Reflection
Example HOW TO pages
TBD
Example Device-specific pages
TBD
Validation
HOW TO pages
- Reviewed / tested by
- ROM maintainers for at least one device per major manufacturer
- one or more 'non-techy' volunteer(s) recruited from the /e/ forums
Device-specific pages
- Reviewed / tested by
- ROM maintainers for the device
- one or more 'non-techy' device user(s) recruited from the /e/ forums