Community-created Simple User Guide

But now with this Forum and it’s ability to have wiki-style posts
(everyone can edit, but with history) we have a new tool with an even
lower barrier to entry than GitHub.

Nothing is stopping us (the community) from creating what @Nina is
asking for and publishing it the way the guidelines call for it.

I had no idea that was a capability with the forum—huzzah!

Yes, Freedom of The Press Foundation’s training team has already put together materials for a “Qubes For Dummies” kind of training. Same, with Insurgo. I’m due to chat with Thierry at Insurgo about his training experiences, and will get some good additional insights from that. @deeplow is also endeavoring as his masters’ thesis, a “Qubes 101” sort of artifact.

If @deeplow would be keen to partner with me on this, and others on the core team and in the community would be keen to support the creation of such a resource, I’d be happy to volunteer to get an initial draft going in a few weeks. Paid work obligations, regrettably, stiffing my availability to work on such an artifact, until then.

Thank you for the cando/sodoit kick, @Sven!

2 Likes

Yep, thanks @Sven for your guidance. :+1:

@ninavizz @deeplow When the time comes to start putting these docs together, I’d be happy to help with what I can. (Taking advantage that my own getting started is relatively fresh :slightly_smiling_face:)

2 Likes

Amazing discussion here. Since it had gone way beyond the scope of the issue, I have split it into another discussion.

Comments / ideas from my dissertation

Well, to be frank I believe what Qubes really needs is a good onboarding. In my dissertation I’m working on an integrated onboarding tutorial, which does tackle a bit of this. But is way less resource efficient than any well produced guide or video. However, I’m constrained by the fact that I am in an engineering degree and making solely documentation would probably not appease the jury :sweat_smile: .

Non-gradual Documentation

I did some interviews with Qubes users and I also got people saying very good things about the documentation and others saying that it had not been useful to them at the beginning. (I should publish some of these results). One of the most insightful comments about the documentation was something along the lines of:

It is written from the perspective of “you know what you’re
doing”. And usually time that you look at the documentation is when
you don’t.

I’ve been there and I know what the user means. The documentation is really great as a reference material, but users have different needs at different times. So all the work invested by @adw and other community members into the docs were well invested and really appreciated! It’s just that there is also the need for another kind of educational resource.

Quoting from the phenomenal “Teaching Tech Together” book by Greg Wilson (can’t recommend it enough for those interested in user education):

The cognitive differences between novices and competent practitioners underpin the differences between two kinds of teaching materials. A tutorial helps newcomers to a field build a mental model; a manual, on the other hand, helps competent practitioners fill in the gaps in their knowledge. Tutorials frustrate competent practitioners because they move too slowly and say things that are obvious (though they are anything but obvious to novices). Equally, manuals frustrate novices because they use jargon and don’t explain things.

A while ago I was trying to visualize the links between documentation pages. I believe this visualization highlights the inter-dependencies of knowledge (i.e. traces of “reference material”):

If it were a gradual resource we would possibly a directed acyclic graph (i.e. links only to previously covered content). Something like the picture on the right. This would serve as a basis for what is called a “learning trajectory”.

Theory aside, all I mean to say is that I fully agree that there there is a need a more user-centered practical guide to Qubes that serves a different purpose than the documentation. And I think it could be a result of the community work.


Count me in!

Count me in! I’ve already made some initial work for my thesis in splitting up information into “lessons”, which could be useful.

As @sven pointed out, a wiki-post on forum may be a good place to draft such a resource (in the #user-support:guides). Apart from the side-by-side markdown visualizer we can also drag-n-drop pictures.

@gonzalo-bulnes I think insights on user documentation are very welcome. I first learned about the Divio’s documentation system on this issue you opened: Re-organize translation docs by Divio's system by gonzalo-bulnes · Pull Request #141 · freedomofpress/securedrop-docs · GitHub. And also, from you and other “fresh” Qubes users is of the upmost importance!

4 Likes

@Nina wrote:

Creating a “(simple) User Guide” and “(detailed) Documentation” as
two separate entry-points, feels like a solution I’d like to work
towards.

Maybe we can get the simple user guide done as a community project
without burdening the core developers?

@Nina would you give us a very rough outline structure of you think is
needed – nothing fancy, just a starting point so there is no blank screen?

We could make that into a Wiki-Post (everyone can edit, but we have a
history of all edits … just like on Wikipedia).

This would be an excellent way for everybody in the community to
contribute and also be a good learning and discovery experience.

Once we have a meaningful result, we could publish it on it’s own
website and link to it from the Qubes OS website.

Shall we try?

5 Likes

I have been hoping to do something like this myself so I’m willing to support this effort!

I’ve had some ideas myself for what sort of information would be helpful for newcomers.

2 Likes

I’ve had some ideas myself for what sort of information would be helpful for newcomers.

Do you feel like summarizing and posting your ideas to this thread? This
way we could collect ideas from you and anyone else who has them and
start discussing / fleshing them out.

There is no reason that our starting point has to come from @Nina. We
can take her input and merge it with whatever we already have.

Writing is always messy. Let’s collect all we can, flesh it out and then
discuss what/where/in which order. Nothing is wasted, as even parts that
might not end up in the “simple user guide” can be harvested and
contributed to the community documentation.

I think there are a lot of people who want to contribute / give back to
Qubes OS but don’t see themselves becoming Xen/Kernel experts or even
writing Python GUI code. But everyone who uses Qubes OS can contribute
to this!

One thing I can commit to right here and now: I will translate the end
result into German.

3 Likes

Please go ahead and summarize some ideas in this thread!

I honestly think the best possible starting-point output, would come from an asynchronous workshop… in a tool that allows for post-it-note fidelity-level rearranging of information in small bits. Bits that are visual and prevent participants from writing sentences upon sentences, or getting too granular into detail—and allow for easy moving-around of parts and creation of more parts. All of which can be visible at once. Which is why post-its on big blank walls are so delicious.

Most of my participation I think, should just be in moderation—as I am not a power user of Qubes, but am very aware of where non-Linux-native users have struggled in their adoption and learning curves. I’m also a UX practitioner by trade, and can setup some guiding principles and guardrails to guide others in actually “Creating” the goods. If that makes sense.

Once that workshop is completed and there’s a solid group consenssus around what a 10,000ft view should look like, drafting in a wiki can begin.

I posted this in the other thread, but will share again here as a reference point. In regards to how information is “bucketed” hierarchically, and nicely segmented into cognitively accessible bites—UXPin’s documentation is a good example I’ve been using a lot lately for the App Menu redesign project: https://www.uxpin.com/docs/getting-started/downloading-and-using-uxpin/

2 Likes

Unless you or someone else knows a FOSS solution, I’d be willing to sign up for a Pro account with https://ideaflip.com/ and invite you all as guests onto the board. I expect we will finish this first async workshop phase in 1-2 months top and won’t need the board after that.

1 Like

Whoops! I’ve had to do some weird merge of topics here as the discussion diverged into another topic which I only noticed after I had split the thread from the original discussion. But despite some posts not being in chronological order, I believe it hasn’t lost any meaning.

@sven in these situations you can keep discussing on the original thread (even if it’s no longer on the same subject). Just point out to me to split the thread like this user did here. Otherwise my merge-foo trickery doesn’t work so well :slight_smile: . But I appreciated the initiative! (also, I’ve given this topic the title of your other post).

For what is worth, I took a few notes before deciding to prioritize writing down my learnings on using Salt in Qubes OS.

I wrote those down before learning about the Divio’s documentation system that @deeplow mentioned above, and haven’t revisited them since I put them on hold. My intention was to move them to my public notes eventually, but as @Sven said: it’s often easier to start somewhere, so if those are useful I can move them (or any useful bits) to the forum.

2 Likes

Project Management

I’ve attempted to consolidate all the ideas for this project on the first post. I’ve also added there a list of interested contributors and roadmap for the project. I have made it into a wiki post so anybody can contribute.

Here’s a sneak-peek:

1 Like

Some months ago, I wrote a module for the German BSI IT-Grundschutz (IT Baseline Security Manual). The text is rather shortb and somewhat formal and mostly contains requirements on what to do or not to do in order to use Qubes in a secure way. It is still not officially published - the BSI is a governemt office and thus not too fast :slight_smile: -, but you are free to use any part of it that might be helpful. You’l find the text at the issue IT-Grundschutz Module for Qubes Client.

@Sven This text is already available in English and German.

3 Likes

I have just pinged awokd, the Qubes Community maintainer (over on github) about this.

2 Likes

@Sven re: Ideaflip… I’ve been using (and have had a paid subscription for) Miro, for a while now—and have used it with other FOSS ux teams. The latter, has me believe there’s not a decent FOSS solution just yet. Ideaflip looks really neat, though! I think anyone can collaborate on a board I “own” in Miro, without them having paid accounts. I need to see, first. My other boards are somewhat sensitive and I don’t want to be public, so I need to fuss around a bit to figure this out.

@deeplow the UXPin link, was simply to it’s documentation as an example of docs that follow UX best-practices for content navigation and consumption. Well thought-out information architecture, small and easy to consume chunks of content. Never a whole page of scrollable text, 5-second looped animations to demonstrate simple interactions. Simple, plain language that rarely forces the user to look at a glossary. It all seems minor, but in totality adds-up to serve users well who don’t have the time to do a full onboarding… and then dive into the tool. Without the latter, onboarding learnings are often forgotten. Personally, I’m the classic impatient user… if you can’t tell. :smiley:

Sven & Deeplow: BTW, can I tell you both how superbly cool it is for someone to volunteer to effectively PM an effort? Like, Andrew is the PM of all these things by default, but is stretched so thin already.

I need to (regrettably!) ignore this thread for the next few days, but will be meeting with a colleague in the next few days to get a download from her on effective async workshopping. @deeplow I think we need BOTH what you’re creating, and perhaps what we’re creating, here? I certainly trust that what you’re creating, our journalists at FPF and Insurgo customers, will really, really be hungry for. I can’t wait to check it out! If anything, I think they could be wonderfully complimentary artifacts.

3 Likes

(and, yes, I am ragingly hypocritical slapping the cane on my palm while bellowing “Small, consumable content chunks!” in lengthy conversational diatribes, here. Discussion vs Documentation, heh)

Sigh. You’re really going to make me copy/paste from the link, aren’t you? “The community is better positioned to write and maintain documentation that applies, combines, and simplifies the official documentation, e.g., tutorials that explain how to install and use various programs in Qubes, how to create custom VM setups, and introductory tutorials that teach basic Linux concepts and commands in the context of Qubes.”

Think of the Qubes OS Project as making the engine for your car or the CPU for your personal computer. They write technical manuals for those artifacts, but those technical manuals are meant to be consumed by other technical people, not by non-technical end users. The manual for an engine is not the manual for a car. A CPU spec sheet is not a personal computer manual. Someone further down the chain, closer to the non-technical end user, is responsible for making things easy to use for consumers. If we had enough resources to vertically integrate this supply chain, we could do it all ourselves, but we don’t. The core documentation is largely a volunteer effort and is barely sustainable in its current state.

And your post isn’t? Hint: Everyone else’s text is a “wall” when you don’t like what it says or don’t feel like reading it (but never your own).

That page is part of the developer documentation, and it’s about contributing to the documentation. It’s not for end users who are merely using Qubes. If you’re contributing to the documentation, “thinking” should be a prerequisite.

Do you think we don’t understand that users don’t want to have to think? That things should “just work”? Have you considered the possibility that we understand and share that goal but that the reality of the situation has led us to what you currently see?

Don’t wish it. Write it!

A worthy goal. Make it happen!

“Many contributors do not realize that the there is a significant amount of work involved in maintaining documentation after it has been written. They may wish to write documentation and submit it to the core docs, but they see only their own writing process and fail to consider that it will have to be kept up-to-date and consistent with the rest of the docs for years afterward. Submissions to the core docs also have to go through a review process to ensure accuracy before being merged (see security), which takes up valuable time from the team. We aim to maintain high quality standards for the core docs (style and mechanics, formatting), which also takes up a lot of time. If the documentation involves anything external to the Qubes OS Project (such as a website, platform, program, protocol, framework, practice, or even a reference to a version number), the documentation is likely to become outdated when that external thing changes. It’s also important to periodically review and update this documentation, especially when a new Qubes release comes out. Periodically, there may be technical or policy changes that affect all the core documentation. The more documentation there is relative to maintainers, the harder all of this will be. Since there are many more people who are willing to write documentation than to maintain it, these individually small incremental additions amount to a significant maintenance burden for the project.”

So, the key questions are: Who’s going to help maintain it, and for how long? Usually people get all excited about writing a new piece of documentation, submit it, then promptly forget about it and move on with their lives. It then becomes my job to take care of it for eternity, and as these all pile up, it’s just not sustainable. Look, if this new guide is as good as you say, then we’ll be happy to have it as part of the official docs for as long as it gets maintained. But if the maintenance burden becomes untenable, we’ll have to triage it, like we just did with the community doc migration.

I think it would be more useful to leave it on this forum than to publish it on its own website, unless that other website is the existing Qubes Community website. (Might even be worth considering merging Qubes Community into a guide/wiki section of this forum.) Let me be clear: A lot of people complain about the Qubes documentation, but not many people are willing to lift a finger to do anything about it. Those people should be the change they want to see in the world. Everyone should follow Sven’s lead here and help write the documentation that you think is missing or bad, and if you can’t write it yourself, persuade others to help you.

4 Likes

@adw I think we can essentially distill your post into:

  • Make it happen
    Worthy goal, make it happen!

  • Maintenance is a burden
    Make people commit to it before publishing it!
    @adw will (understandably) not be doing maintenance work for us.

  • Publishing
    If it that good, it can go on the official docs as long it gets maintained.
    If too burdensome for review, it’s gonna go elsewhere like the external docs did.

Did I sum this up decently?

Also, I think a corollary of this is that we should make it maintainable by design. By this, I mean, make it as short and update-avoidant as possible.

Excellent points @adw and good summary @deeplow . To the point of “Maintenance is a burden” one of the approaches I would advocate is develop documentation on the concepts and bigger picture as opposed to the “tool”. Tools can come and go, but fundamentally what Qubes is doing is trying to teach us new habits in how we interact with a computer. The habits that we can apply in other contexts, mobile devices, or online behaviour, etc.

So, maintaining documentation about Best Practices, or concepts don’t have to be constantly changing, like tools do.

So, my approach to the documentation was to focus on getting these types of thoughts into words. I deal with these types of things everyday in my day job.

1 Like

@adw I understand where you are coming from. I have doubts that the end result would fit nicely into the forum but maybe I need to learn more about Discourse and it’s abilities. Some GitHub pages kind of thing that feeds out of the Qubes Community repo would probably do the trick.

But also this topic: let’s postpone it until we have the actual content. I hope we can get the brainstorming/workshop part of it going soon.

1 Like

Maintenance is a burden

It definitely is. One thing for sure is that as soon as R4.1 rolls out
we will have to update all of the screenshots. And I think we will
have many of those.