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:
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 
-, 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.
@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. 
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.
(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.
@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.
@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.
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.
Gah, I left my sprinklers on!!! Thx for the reminder!
I am also behind the 8-ball with needing to wrap user testing for the App Menu to meet funder obligations. My work on the “Simple User Guide” is volunteer, but folkx I’ve mentioned it to are very excited about it… and tbh, I am too!
I’ll be doing “homework” next week on how to best setup async workshops to get the most out of everyone’s participation, with the least amount of time involved for everyone. Thx for the note, and enjoy some time outdoors!
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.
Totally get where you are coming from @zks1 and such a verbal
description of the best practices would be a wonderful thing to have.
Ideally we would end up in a couple of years with an entire book
describing the ideas, principles and best practices of Qubes OS as well
as the architecture and a bit of the history dream
However when talking about “simple user guide” and a “getting started”
we need to find a way to transport those principles in as few words as
possible. Screenshots, graphics and maybe even little videos will be
essential to not overload new users.
Think about people we are targeting with this: all of their attention
and energy is with the thing they are doing (reporting, researching,
communicating, defending a client) and the need for a secure environment
is just that: a need that arises out of what they are doing. We need to
get them to understand the what, why and how as frictionless as possible.
That needs to be visual as much as possible and those visuals need to
match what they see on their own screen … otherwise it’ll confuse more
than help.
Yes, I feel like our goal would be to having something practical for the user. One maintainability trick I’ve heard recently is to have emojis whenever possible instead of screenshots. Example:
» Appearance » select “adwaita-dark”.People can still map emojis onto the interface (even if it changes slightly).
Hi, hi! Still crawling out from under my rock of catching-up. The appmenu work is almost completed, from my end—and next week, I should have time (really) to begin re-engaging on this. Apologies for the continued delays, but I am quite excited to get this together, too. <3
For what it’s worth - I have been planning on putting together some initial walk-throughs on basic tasks like installing and configuring Qubes for the first time, migrating VMs from other platforms over, and other lessons learned. Long before this forum existed, I had this planned. Originally, I figured I would just toss this up on Medium and let whatever search indexers are out there guide users in.
BUT.
If there is a larger community driven effort, I would happily participate. Perhaps there is a sign up sheet that I do not know of. If so, please forgive me for interloping on this interesting conversation.
Apologies for the continued delays, but I am quite excited to get this together, too. <3
All good, just making sure we are not loosing momentum on this. Let me
know how I can help when you are ready.
If there is a larger community driven effort, I would happily
participate. Perhaps there is a sign up sheet that I do not know of.
If so, please forgive me for interloping on this interesting
conversation.
Awesome! There will be an “asynchronous workshop” soon moderated by
@nina. We will make a lot of noise in the respective forum threads when
that happens, you won’t be able to miss it 
Nice! Just add yourself to list of interested contributors on the first post (you should be able to edit it).
Seems so. Added myself.
