Docs: "Getting Started" section enhancements

[ninavizz]

The problem you're addressing (if any)
The "Getting Started" section is currently written in such a way that advanced users will understand, but that is likely burdensome or alienating to more novice users.

Describe the solution you'd like
If I knew how to do PRs, I'd take the initiative to propose these changes vs creating an Issue to describe them (this). I'd be happy to collaborate with someone, if anyone might be up to do some hand-holding with me. BUT, I also don't want to go and "mess up" an artifact many others have worked very hard to curate in a very specific way I am probably unfamiliar with.

• Rename "Introduction" to "Working with qubes and templates" (or something more specific to content)
  • Content speaks more to the basics of working with qubes and templates
  • "Introduction" presumes to know where a user's learning curve is, which we do not know
  • Possibly re-order with the GUI section, so that this is the second section and it is the first? It feels like its putting the cart before the horse, to explain an ecosystem before explaining at a basic level, how folks can just simply get around.
• Move "GUI & Command Line Tools" to become the first section
• Rename "GUI & Command Line Tools" to "User Interface"
  • "GUI" is technical jargon that developers and tech people will know, and possibly some Linux folks—"User Interface," more people will understand, and communicates the same basic principle. That this content speaks only to graphical user interface tools and not CLI tools, is a distinction that only developers or hardcore technical users will pick-up on—and cannot negate making the section name intuitive to the people who most need this content.
  • In the first paragraph, speak explicitly to technical users desiring command-line tools to navigate. Then, the existing content to that effect.
  • Next, introduce paragraph that speaks to the following points:
    • For users new to Linux: Most of what is exposed as a user interface is called a "Desktop Environment," and exists within the primary administrative qube which uses the Linux OS (distro) Fedora.
    • The DE Qubes comes with is XFCE. Provide link-out to learn about XFCE.
    • Identify which parts of the Qubes UI are controlled by XFCE (App Menu, Spaces, Task Bar, Tray, Window Management, ??)
    • Identify which parts of the Qubes UI are custom (Domains Widget, Devices Widget,
    • Identify which parts of the Qubes UI are from other third parties (Whonix, ??)

Where is the value to a user, and who might that user be?
Users not familiar with Linux, or whom are simply not technical.

Describe alternatives you've considered
Making a community-created user guide, which is a separate project and will be happily contributing to. The above basic changes should still happen in the primary docs for Qubes, as they currently presume much more technical knowledge than any of the users I work with, regularly, have.

[ninavizz]

@hackerncoder Thoughts? I've learned some BASIC GitHub stuff, recently... and maybe could do most of this. I'd need some help doing the pull/push/commit parts, tho, and would want your thoughts wrt keeping inline with @andrewdavidwong's curatorial goals.

[andrewdavidwong]

If I knew how to do PRs, I'd take the initiative to propose these changes vs creating an Issue to describe them (this).

Have you tried following this guide?

https://www.qubes-os.org/doc/doc-guidelines/#how-to-contribute

[ninavizz]

If I knew how to do PRs, I'd take the initiative to propose these changes vs creating an Issue to describe them (this).

Have you tried following this guide?

https://www.qubes-os.org/doc/doc-guidelines/#how-to-contribute

The "Edit This Page" links at the bottom that the above page points to, do not exist for this page:
https://www.qubes-os.org/doc/getting-started/

Also, I literally do not know how to do the "...all you need to do is" stuff. Git is hard, for those of us unable to code. I've been stepped-through the process a few times. It took over an hour just to get me to clone a repo, last time. :D

Yes, you have trained me better than to NOT RTFD before posting such vageusauce, as posted above.

[ninavizz]

It's also unclear how to edit the static text on: https://www.qubes-os.org/doc/

As such, I created a public GDoc. Edit suggestions are in yellow. Yep, I'm aware there are dependencies/implications if named things are changed there, across other pages.

A public link to the current "Getting Started" page that I'd like to rename the "Overview" page, is here. Happy to create/attach PDFs if desired.

Sorry I'm not yet up to snuff with GH to do it all, here. Working on that.

[andrewdavidwong]

The "Edit This Page" links at the bottom that the above page points to, do not exist for this page:
https://www.qubes-os.org/doc/getting-started/

Ah, crap. Using a different layout was an intentional decision, but now I think it's doing more harm than good, so I've changed this page to use the standard sidebar layout that the rest of the docs use (QubesOS/qubes-doc@c0e7729). The "Edit This Page" button should now be there.

You should be able to follow the guide now. You don't have to know any Git or use the command line at all. It should be pretty straightforward.

It's also unclear how to edit the static text on: https://www.qubes-os.org/doc/

It's already documented on that page, but it's probably too easy to miss. I've just made it more perspicuous (QubesOS/qubes-doc@6043c6e). You'll encounter it as part of the guide now.

(Our plan is to automate the doc index for all core docs soon, so this separate step will eventually become unnecessary.)

As such, I created a public GDoc. Edit suggestions are in yellow.

A public link to the current "Getting Started" page that I'd like to rename the "Overview" page, is here.

I do have some objections to these changes, so we can discuss them on your GDoc first, if you prefer to do that on the GDoc rather than in a PR.

[andrewdavidwong]

Yes, you have trained me better than to NOT RTFD before posting such vageusauce, as posted above.

Ok, but you never said that you read the appropriate docs. I have no way of knowing what you have and haven't read unless you communicate that to me. This is precisely why we have a special section in the issue template called "Relevant documentation you've consulted" (which you removed) and why we specifically say to use the issue template:

When you open a new issue, an issue template is provided for you. Please use it. Do not delete it. The issue template is carefully designed to elicit important information. Without this information, the issue is likely to be incomplete. (If certain sections are not applicable, you may remove them, but please do so only sparingly and only if they are truly not applicable.)

[andrewdavidwong]

(Also added the HTML comment boilerplate about not deleting the issue template and reading the doc guidelines to the enhancement and task issue templates to make it harder to miss: 38038d2)

[andrewdavidwong]

I do have some objections to these changes, so we can discuss them on your GDoc first, if you prefer to do that on the GDoc rather than in a PR.

Requested edit access. (I actually only want the ability to leave comments.)

[ninavizz]

@andrewdavidwong I'm not a developer. I'm just looking for simple, discoverable answers. With the same willingness to "find information" as regular users of regular consumer products are. If it takes reading through the entire docs to find an answer, I don't feel that's reasonable. That's a huge part of usability work—making it so users don't have to read through an entire artifact, to find an answer to use a product. That's information architecture.

That needs to be considered reasonable grounds to desire changes.

If you feel up to making recommendations in the GDoc, that'd be great! But, do note that the longer GDoc I only took a light pass at. The writing was approached, intentionally avoiding a deep-dive into everything up-front, and trying to disclose information sort of as progressive JPGs load; provide an initial basis for users to get their heads around, and then fill in more blanks with each successive paragraph/section as appropriate.

[andrewdavidwong]

@andrewdavidwong I'm not a developer. I'm just looking for simple, discoverable answers. With the same willingness to "find information" as regular users of regular consumer products are. If it takes reading through the entire docs to find an answer, I don't feel that's reasonable. That's a huge part of usability work—making it so users don't have to read through an entire artifact, to find an answer to use a product. That's information architecture.

That needs to be considered reasonable grounds to desire changes.

I have no idea what you're referring to. You could be referring to the PR process for contributing to the docs or the content of your own proposed changes to the documentation.

If you're referring to the PR process: I mean, you're trying to edit the technical documentation of a high-security software project. That's something open-source collaborators do, not something most "regular users of regular consumer products" do. I think your expectations are off here. The GitHub web interface makes it quite easy, if you give it a try. Probably much easier than you're expecting.

If you feel up to making recommendations in the GDoc, that'd be great! But, do note that the longer GDoc I only took a light pass at. The writing was approached, intentionally avoiding a deep-dive into everything up-front, and trying to disclose information sort of as progressive JPGs load; provide an initial basis for users to get their heads around, and then fill in more blanks with each successive paragraph/section as appropriate.

Sure, I'll leave comments on the GDocs when I get access.

[hackerncoder]

@ninavizz Seems good. I'd be happy to help you (though we should probably establish contact somewhere else than qubes-issues). I've also done some of it, QubesOS/qubes-doc#1153

[ninavizz]

@andrewdavidwong I was speaking to the docs, themselves, with this:

I'm not a developer. I'm just looking for simple, discoverable answers. With the same willingness to "find information" as regular users of regular consumer products are. If it takes reading through the entire docs to find an answer, I don't feel that's reasonable. That's a huge part of usability work—making it so users don't have to read through an entire artifact, to find an answer to use a product. That's information architecture.

That needs to be considered reasonable grounds to desire changes.

I'm speaking as a usability practitioner. From many years of experience.

Right now, the docs do not follow user-centric best practices for structuring content in a fashion that maps to how users' brains process information. Cognitive processes that support both learning, and later with reference tasks—but primarily, learning. Neither should (or have to) exclude the other.

The docs, today, are structured following norms and standards I've observed for developer documentation, and encyclopedic structuring of knowledge. Which, for the developer sections, are fine. But for the "How to tangibly use this thing" sections, discourages engagement. So people go to forums, or they abandon the product. My goal with these edits, is to reduce both of those things. So, in effect, to make all of our lives easier—while also making it easier for users to initially use Qubes.

[ninavizz]

Ok. Backing up just a bit...

The goal with this Issue is two-fold:
1. To relieve the "cognitive bottleneck" created by presenting a metaphorical tidal-wave of information in the beginning and in a seemingly chaotic fashion. With all instructional text, you have to pick and choose which "pieces" you start with—such that users can be given an opportunity to build their knowledge in an atomic fashion from a simple, solid foundation. Like: today "Security Domains" are mentioned before "Templates" are. That creates confusion.

There are also many parenthetical statements throughout today's "Getting Started" section, that are distracting and disengage cognitive processes from retaining foundational information. While I suspect their intent is lighthearted and to offer clarity, their impact works against knowledge being retained. When everything should be a priority, nothing ends-up being a priority—and establishing foundational knowledge needs to be the priority, for the first section.

2. To make things more intuitive for users to find, in the beginning and as they learn.

"User Documentation" is not an intuitive header for a section we want users to go to and learn from, at the outset. RTFD is a funny acronym, because so often people don't RTFD. We need to make it easier for them to do that, more than we should be prioritizing topical accuracy. Findability and topical accuracy in the encyclopedic sense, are very different concepts that need to be blended, if in fact people actually using a thing is desired. Because, humans gonna human.

By meeting users "where they are" with the assumption they know about Qubes conceptually but not about the specific parts of Qubes. It is to embrace a concept in cognitive psychology known as "Working Memory" that Miller's Law speaks to. TL;DR, when learning new things you can only retain so much. So, if knowledge is dispensed progressively vs in a tidal-wave, the success of its retention and compreheion, both, are far higher.

[deeplow]

Right now, the docs do not follow user-centric best practices for structuring content in a fashion that maps to how users' brains process information.

I think the fundamental issue here is is that the documentation is written as a reference. In that aspect it is well put together.

A getting started seems to me like it has a different goal. And I don't think they are incompatible. It's just that the difference of purpose (resulting in a difference in form) needs to be recognized. I have a longer explanation of this on the forum.

I would suggest the following:

1. For the "getting started" page only
   - dropping all traditional concerns other documentation pages have
   - focus exclusively on learnability (points (1) and (2) @ninavizz raised in the previous reply)
2. Leaving all learnability issues beyond the scope of the "Getting Started" to the community-created simple user guide
3. for other concerns about the Findability and topical accuracy beyond the scope of this page, opening a new issue or making a Pull Request directly.

[andrewdavidwong]

This might already be obvious to many of us, but it's worth stating for the record (since no one has mentioned it in this issue) that the content of the Getting Started page should be integrated into the software of Qubes OS itself as part of an onboarding experience rather than existing as separate documentation. I know @deeplow is already working on integrated tutorials, and I think I've heard @ninavizz discuss this too, so I assume we all agree and that this documentation is just a temporary stopgap until we have an integrated onboarding experience.

[deeplow]

I see. On the onboarding tutorial I'm introducing the user to the "Qubes menu" and the Domains Widget. But I don't really do a tour of the other widgets or the creation of Qubes. That could be something for another tutorial. But in any case I'm trying to make the code flexible to allow changing it to include more stuff if needed.

[ninavizz]

I think the fundamental issue here is is that the documentation is written as a reference. In that aspect it is well put together.

I actually disagree with some of that, for the purpose of serving end users. Which I don't say to be argumentative.

The page as it is written today, is actually quite all-over-the-place; and, it jamms waaaay too much information w/o context, into a user's brain—with multiple segues. Which I say, largely from having read ¡a far-better version! written last night by a vampire (cough, Andrew) parallel to what the conversation thus far has suggested. It is well on its way towards getting there!

Headers are critically important for findability of content, and for ~80-90% of the docs I'm fine leaving to follow developent documentation standards—but for this one section, I want the headers to be intuitive enough to invite non-developers to engage with. Once folks get their feet wet in our FOSS world, hopefully that can encourage them to brave the rest of our documentation—and its wealth of well-organized written concepts strange and intimidating to non-technical or non-FOSS-y folk.

The "Community Guide" I also really look forward to working with y'all to develop—but this Getting Started page still needs a lot of work, to effectively serve users. :)

[andrewdavidwong]

I think the fundamental issue here is is that the documentation is written as a reference. In that aspect it is well put together.

I actually disagree with some of that, for the purpose of serving end users. Which I don't say to be argumentative.

The page as it is written today, is actually quite all-over-the-place [...]

He was referring to the documentation in general, not this specific page.

[ninavizz]

I am still almost crying, as I re-read your updated text @andrewdavidwong... it is SO GOOD!! Getting a lot of ideas, too, for really basic illustrations to add-in. Might work on some of those this weekend—but for now, will insert short descriptions in brackets, inline.

[ninavizz]

Also, fwiw—the illustrations, for the most part, I see as being very optional. I'd love to add them eventually, but have no idea when I'll have the bandwidth to really make them fabulous. This updated text is far better than what exists today, and if this text were to get pushed in a PR I'd just cheer a whole lot.

[ninavizz]

@andrewdavidwong Ok, I added a few more structural edits, made a couple "Suggestions" in suggest-mode, and added a picture. I'd be delighted to see it as it is, now, replace the existing "Getting Started" page—and to then add-in illustrations as I'm able to make them.

I also totally agree with the other "Separation of learning materials vs guides vs docs" themed comments in the other GDoc, but feel that's a much bigger project. My only concern for now, is to make iterative improvements to what we have, such that developers and users of all capabilities, can intuitively find what they need. Within what we have.

[deeplow]

Amazing refactor @andrewdavidwong. This was very much needed.

[andrewdavidwong]

Amazing refactor @andrewdavidwong. This was very much needed.

Thank @ninavizz too. Teamwork!

[deeplow]

Amazing refactor @andrewdavidwong. This was very much needed.

Thank @ninavizz too. Teamwork!

Absolutely! @ninavizz you too :)

In two afternoons two people compose an introduction way more detailed than the tutorial I've been working on for some months. Haha.

[andrewdavidwong]

In two afternoons two people compose an introduction way more detailed than the tutorial I've been working on for some months. Haha.

I'm sure it'll be great! Integrated is much harder, but also much more likely to be consumed. 🙂