This page contains the details of a technical writing project accepted for Google Season of Docs.
Project summary
- Open source organization:
- Qubes OS
- Technical writer:
- luzeal
- Project name:
- Onboard with QubesOS ! Let's write an open and easy-to-use guide
- Project length:
- Standard length (3 months)
Project description
Onboard with QubesOS !
I would like to create an open guide and related materials for first-time QubesOS users. The goal would be to introduce QubesOS to the layman, and to keep the guide as consise and comprehensible as possible, using analogies, illustrations and diagrams. In order to keep it consise, links to reliable and trusted resources will be used, including first and foremost those present in the QubesOS website. Everything will be released under an open license.
By standalone, I mean a piece of content that could exist independantly of the website, for instance as an handbook. It doesn't equate with the offline version of the guide. Ideally, another pipeline to publish the content as a guide will be created, alongside the website.
By open, I mean a guide which will be released under an open licence.
How it might be done
Define the target audience
As of today, I have the impression that the category of users that QubesOS is targeting is not well defined. How can QubesOS help journalists, lawyers, security analysts, software developers and so forth ? It would be enlighting to describe scenarios in which QubeOS can prove useful.
Set expectations right
It would also be important to warn first-time users that QubesOS requires a fair level of IT knoweldge. There is a price to pay to use QubesOS, usability-wise, especially if QubesOS is your primary computing system. On the same token, there are things that QubeOS won't do well (by design), such as 3D acceleration in virtual machines. It is important to make it clear from the get go, not to deter people from using it but to set exceptations for potential users.
What QubesOS is and what QubesOS isn't
Even though QubesOS is a special breed of operating system (a Xen distribution), it would be interesting to compare it to other operating systems based on their functionnalities or lack thereof (for example, Windows is increasingly using virtualisation and sandboxing as security mechanisms.). A simple diagram/table could be used.
Specifications for the guide will be defined with the community.
What is the minimum information that the guide should contain ? How much can the installation be simplified without sacrifing security ? Where should the threshold be ? Is there such thing as a minimally viable and secure QubesOS set up ? If no, it could be defined and set as the target for the guide.
License
Pick up a license. The well respected Archlinux wiki is using GNU Free Documentation License 1.3 or later. Would this licence be a good fit ?
Other endevoars
Make website documentation more visually appealing
Notes could be highlighted using red or yellow colouring in order to make them easier to notice. For instance, color boxes could be used, such as those found in the archlinux wiki. https://wiki.archlinux.org/index.php/Linux_Containers.
Blockquotes could be used.
Link contents
There is currently quite a lot of content for the documentation website, but the individual pieces are often not linked to other relevant topics. Articles could be linked to each other, to improve discoverability.