Qubes OS is a complex piece of software. It doesn’t work like any operating system out there and as a result, it is challenge for newcomers or even more experienced users to understand how it works and what it does, at least when browsing the current website.
My goal has been to make it easier for first time users to comprehend and to use Qubes OS by suggesting improvements to the introduction page and to the installation guide.
For instance, I have adapted an existing diagram so that anyone can understand Qubes’ architecture without having to read pages of text. I have also emphasized what I believe are the main functionalities of Qubes OS.
When it comes to the installation, I have documented each step of the process to install Qubes OS, a process that wasn’t documented previously.
SUMMARY OF THE CURRENT STATE OF THE PROJECT
As of now, besides some screenshots, nothing has been merged to the main project. Pull requests are open, and some back and forth is still needed before my changes could be incorporated (see links below).
CHALLENGES & LEARNINGS
On a personal level, one of the main challenges has been balancing work on the project alongside other side projects and a full-time job. The fact that English is not my mother tongue has also added a layer of complexity.
When it comes to the project, I believe that the process to suggest changes is still cumbersome and may deter people from contributing (non-developers are likely to struggle, as there are many sub-modules in the current repo, for instance, which make it extra hard to contribute to the website). It is relatively easy to submit a pull request, not so much to revise it. Perhaps that could have been a project in itself : how to make it easier for people to get onboard/contribute. The fact that the project is security-oriented makes it extra-hard to contribute.
There is already quite a bit of documentation written for Qubes OS. However, the articles are scattered and are not all linked with one another. It is not easy to add something new as you have to modify what’s already there, and rather than adding something new, a reorganization or enrichment of what already exists may have been a better pursuit.
Throughout the project, I got many suggestions from different people which were sometimes in conflicting or diverging, and I was not always sure which to prioritize. Everyone has good ideas, but they do not necessarily agree with one another.
I appreciated the opportunity to take a closer look at Qubes OS’ inner workings and to better understand how the OS works.
I would like to thank Marek Marczykowski-Górecki for his support as well as the wider Qubes OS community for their useful feedback. It has been a positive experience, and I am glad and proud to have had the opportunity to participate in this project.
Improvement of the introduction page :
- Open GitHub issue : https://github.com/QubesOS/qubes-issues/issues/5357
- One pull request : https://github.com/QubesOS/qubes-doc/pull/871
Improvement to the installation guide :
- Open GitHub issue : https://github.com/QubesOS/qubes-issues/issues/5471
- Two pull requests : https://github.com/QubesOS/qubes-doc/pull/899https://github.com/QubesOS/qubes-doc/pull/885
- Qubes OS architecture diagram (R/W):