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 
.
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!