Qubes OS project

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:
c1e0
Project name:
Consolidate troubleshooting guides
Project length:
Standard length (3 months)

Project description

ABSTRACT

A troubleshooting guide is designed to help end-users solve any problems encountered when using a product or service. A good troubleshooting guide is important because it assists users when problems arise. It keeps users from abandoning a product when they encounter an issue. Qubes has thousands of daily users around the world, many of whom will face an issue at some point in time and will benefit from a troubleshooting guide.

CURRENT STATE OF THE TROUBLESHOOTING GUIDE

At this moment, the QubesOS troubleshooting guides are scattered across many pages and sometimes incomplete, leading to repeatedly posting the same instruction over and over when helping users to diagnose problems. The available guides lack a symptom-action layout, making it difficult for a user to match a problem to its solution. In addition, there are some issues that have been mentioned repeatedly on social media (Reddit), the Qubes Github issues page and on the #qubes-users forum, but have not been documented on the current troubleshooting guide.

WHY IS MY PROPOSED TROUBLESHOOTING GUIDE AN IMPROVEMENT OVER THE CURRENT ONE?

My proposed troubleshooting guide will be complete and structured to ensure accuracy and easy navigation. The guide will showcase concise instructions that explain how to solve a problem in a step-by-step manner. It will feature a symptom-action layout, where a problem will be stated, followed by a recommended solution to solving that problem. The troubleshoots will be search-engine optimized and worded to take into account what problems users are searching on social media and search engines. All these will go to ensure that users can find the official troubleshooting guide through search engines and quickly/easily find the solution to their problems

STRUCTURE OF THE PROPOSED TROUBLESHOOTING GUIDE and TIMEFRAME

I have created a proposed structure for the Qubes OS troubleshooting guide which can be found here: https://docs.google.com/document/d/187NlnEvctYVVUnRuGtwY2PkYBVxBSSPfpSwZEaczqL8/edit?usp=sharing. The layout is accompanied by an estimated timeframe during which each troubleshoot section will be written. This layout will be implemented after feedback from the mentor. The structure and timeframe may be modified based on mentor feedback.

PROJECT GOALS

  • Restructure the troubleshooting guide to have a more comprehensible, consolidated symptom-action layout.
  • Rewrite existing troubleshoots to have easy-to-follow step-by-step instructions.
  • Add screenshots where necessary
  • Install and try out Qubes myself and record any problems encountered. I have three computers: a Lenovo Thinkpad, Dell Latitude, and an Acer Aspire. I will try Qubes on each of these computers, recording any errors and validating any troubleshoots.
  • Remove any obsolete information in the existing guide.
  • Ensure the troubleshoots are accurate. As of now, the existing troubleshooting guides have the error message ""This is unofficial, third-party documentation. The Qubes OS Project cannot guarantee the accuracy of this page. Please exercise caution"". This warning will be discarded after the troubleshooting instructions are verified to be accurate. Their accuracy will be ensured by either personally testing the troubleshoots on my PCs (if possible), or checking online if any users have validated the solution.
  • Migrate any external troubleshoots (from the forum and GitHub) to the official troubleshooting webpage.
  • Research and find more troubles faced by users from Reddit (r/QubesOS), Stack Exchange, #qubes-users Google group, and GitHub issues. I will also use keyword research tools like Keywordtool.io and UberSuggest.com to discover what questions are frequently searched on search engines like Google.
  • Add a “Getting help” section, in case the troubleshooting guide doesn't solve the users’ problem. An example can be seen in Fedora's troubleshooting page: https://docs.fedoraproject.org/en-US/fedora/rawhide/install-guide/install/Troubleshooting/#sect-troubleshooting-getting-help.

WHY THIS PROJECT?

I am passionate about technology, particularly cybersecurity and privacy. I believe writing is one of my strongest suits. I'm particularly interested in the Qubes OS because it intersects two major interests of mine: security and privacy. I am an avid user of other security and privacy-focused products like DuckDuckGo and Tor. I only recently discovered Qubes OS, and I am loving it so far.

WHY I BELIEVE I AM THE RIGHT PERSON FOR THIS PROJECT

  • I am passionate about security, privacy, and writing good/helpful documentation.
  • Because I have experienced issues when installing and using Qubes OS, I will be able to better represent these issues in the troubleshooting instructions.
  • In the past month, I've studied the technical aspects of the Qubes Operating System. I have also studied the Qubes OS documentation extensively. To get a feel of the documentation-editing process, I created a pull request (https://github.com/QubesOS/qubes-doc/pull/1005/files)
  • I recently completed an internship at the Tor project. My roles were technical support and writing. While working at the helpdesk, I received hundreds of questions from users who faced troubles when installing or using Tor Browser. By helping these users troubleshoot their problems, I learned how to write concise and comprehensible troubleshooting instructions
  • While working at the Tor Project, I also wrote technical documentation using Markdown. I used Git, GitHub, and GitLab for version control.