Skip to content

Instantly share code, notes, and snippets.

@enjeck

enjeck/report.md

Last active February 13, 2021 19:11
Show Gist options
  • Save enjeck/bfe9b8b28295d88c438b6f6c754ae733 to your computer and use it in GitHub Desktop.
Save enjeck/bfe9b8b28295d88c438b6f6c754ae733 to your computer and use it in GitHub Desktop.
Download ZIP
Qubes OS -- Google Season of Docs report
Raw
report.md

For the second year in a row, Google has run the Google Season of Docs program to bring technical writers and open source organizations together. After missing the opportunity to apply last year, I was excited about being part of the program this year. My proposal to consolidate Qubes troubleshooting guides was accepted \o/

Qubes OS is an operating system which you probably have never heard of, but you should be using if you are serious about privacy and security. Qubes OS is a free and open-source, security-oriented operating system for single-user desktop computing. Actively-targeted individuals, such as journalists, activists, whistleblowers, and researchers will value the compartmentalization that Qubes provides. Instead of having different computers for different activities (such as for browsing, for sharing sensitive information and ), Qubes lets us divide a device into many compartments and it gives us sophisticated tools for securely managing our activities and data across these compartments.

Qubes OS is quite complex to use, especially for non-technical users. There is a need for troubleshooting guides that will help peoples self-diagnose and solve issues that arise when using Qubes. Before I came on board, the troubleshoots were scattered accross many pages and sometimes incomplete, leading to repeatedly posting the same instruction over and over when helping users to diagnose problems. My GSoD project involved writing a consolidated troubleshooting guide, organized in a clear symptom-action layout.

Work done

Layout and timeframe revision

During the the first two weeks, before starting any writing, I had to revise my original proposed layout for the troubleshooting documentation. This initial layout was lacked content. After a lot of research, I expanded upon it, as you can see in my new and improved document layout shared in the Qubes Google Groups forum. While revising the layout, I also revised my timeframe.

Regular updates

After agreeing on the document layout and timeframe, I began actual documentation development. My mentor proposed that I should post regular updates on the qubes-devel forum, so the rest of the Qubes community can know what I'm currently doing and my next steps. Every week, I provided an update on the work done for that week and the plans for the next week. These updates can be found on the qubes-devel forum.

Merged PRs and commits

In total, I made 27 pull requests. Some were minor changes, others involved major improvements and additions. You can find all the commits I made here.

The following PRs have been merged:

Current state of the project

All the pull requests linked above have been approved and merged. I keep to my proposed timeframe, and have done everything I planned to do in my proposal (to the best of my knowledge). The new and improved Qubes troubleshooting guides are live on the Qubes website.

In earlier discussions with my mentor and the Qubes community manager, we decided to split the Troubleshooting docs into "Core" and "External". The rationale for this is to reduce the work load on the core developers. The "core" troubleshooting guides involve main Qubes features, and will be reviewed and maintained by the developers. The "external" troubleshooting docs involve uncommon/unsupported hardware, and these docs won't be maintained by the devs, but by the Qubes community.

The following PRs have been approved and will be merged soon:

Challenges

  • In the beginning, I had trouble setting up a local version of the Qubes OS website on my computer. After a few days of debugging, I eventually figured it out. It turns out I forgot to install a required Podman script. facepalm
  • The biggest challenge was understanding how Qubes OS works. Before I could write troubleshooting steps, I have to understand the problem in question. Despite having knowledge of virtual machines and previous experience working on Tor, it took me a long time to fully understand the technical aspects of Qubes. I found myself frequently checking the docs and glossary for clarification.
  • Another challenge was keeping up with the number of problems being reported on the forum, GitHub and social media. I had to go through hundreds of threads, keeping track of commonly-reported issues and researching how to troubleshoot them. Doing this research took a lot of time.
  • My project involved moving existing content and pages around, as well as adding new content. For each troubleshooting guide (there were about 20 in total), I created a pull request for it. All these changes resulted in a lot of merge conflicts. After one PR was merged, I had to come back to other PRs and fix merge conflicts.

Lessons learned

  • I learned a lot of technical stuff about Qubes, security, privacy and virtual machines.
  • When allocating time for a project, always allow time for roadblocks, planning and setting up the work environment.
  • Be ready to revise your original proposal content and timeframe. Things almost never work as planned.
  • My time management skills have improved. I have learned how to balance a project and school work.

To conclude, being part of the Google Season of Docs program has been the highlight of my year. I will definitely keep using Qubes OS in the future and hang around the Qubes community.

Thanks to Marek Marczykowski-Górecki for his support and mentoring. Special appreciation to Andrew David for his help and for merging my PRs.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment