Where are all the high quality guides? For some reason search only shows About the High Quality Guides topic in this category. Am I tripping? Weren’t there more of them?
3 Likes
There are the community guides in Community Guides - Qubes OS Forum , I’m not sure exactly what are the High Quality Guides mentioned in the linked thread 
.
2 Likes
I am referring to subcategory in community guides
2 Likes
Good point. I guess we never added guides to that subcategory. If someone finds a guide high-quality, feel free to flag it and then we move them there.
1 Like
What are the criteria to qualify a community guide as a high quality guide?
3 Likes
Fair point. we need one. Not sure what was discussed open creation.
- Working one
- Well explained
- Well documented
- Well formatted
- Issue impacts wide(r) range of users.
Just a suggestion to start from.
1 Like
This is quite subjective unfortunately, how do you measure each of these criteria?
2 Likes
I would add well maintained to the list. Although it is only applicable to older candidates.
“Working” is very easy, but well explained, well documented, and well formatted certainly must be expanded upon.
Also, I think “issue impacts wide range of users” is unnecessary. Quality guide can be niche as long as it fulfills other requirements.
For example, check this guide of mine and apply suggestions above
Easy low quality
Pretty much any @deeplow’s guide and many of yours I’d say - high quality guides.
But if the instructions can be understood by a reader and that the guide works, I’m not sure I see a benefit if we come to differentiate “high quality guides” from “guides”. This could make a difference if people had to pay for it maybe, but it is not the case.
If we replace “can be understood” with “easy to understand” or “can be followed without prior knowledge of the topic” it sounds better.
2 Likes
… of a skill level…? Mine guide is easily readable, but novices might not succeed to implement it, because I left too many prerequisites and facts missed, because I wasn’t willing enough to go into details.
I’d recommend a listed expectation for the high quality guides, so the guides are at least uniform and easier to understand. Then a contributor can know what makes the cut and what doesn’t and flag their post for review. Nothing too complicated, just something like:
- Proper usage of headers
- Hide details that aren’t necessary to follow the guide
- Clarity (clear order, clear differentiation of what commands to run and where, etc.).
- Guide can be followed verbatim (no missing steps, no extra steps)
- Clear and concise explanation of any inherent security risks of following the guide or any step in the guide
- Version(s) where the guide is known to work
We could also use the experience from the Community-recommended computers: A high-quality guide must be verified at least by two independent users, perhaps with showing successful logs.
2 Likes
There is a type of technical document called a “Standard Operating Procedure” (SOP) which is pretty much exactly the same as what you’re looking for in a Qubes high quality guide.
SOPs are a common type of document universally used in manufacturing and some other industries. They are a proven way of handling instructional guides and the guidelines of how to write SOPs are well established–I think it would be best to align with this standard because of this and since it crosses over so nicely to what we’re trying to accomplish here.
Key points are:
- Visually organized and consistent across SOPs (i.e use a template)
- As clear and concise as possible (extra info unnecessary for task completion should be moved elsewhere)
- As visual as possible (photos illustrating each step)
- Able to be followed 100% unassisted by rookie employee (or new Qubes user in this case)
To test a SOP, typically the SOP writer gives the document to someone completely unfamiliar with the process and watches as they perform the instructional set. The rookie must be able to successfully complete the task 100% on their own without assistance in order for the SOP to pass. If not then the SOP is revised and tried again with a different rookie.
Nothing too complicated is nice from the perspective of a guide writer, but it will make guides of inconsistent quality because requirements are not explained objectively. In addition, complexity shouldn’t be a problem in the first place because it doesn’t stop a contributor from writing a guide, nor people from finding the guide useful and applying it. It’s just that guide will not necessarily be marked as “high quality”.
My concern with “not too complicated” was the burden on mods who must sort and approve. The thought was making their job as easy as possible while giving some structure to the category. Since they already volunteer their time, it would be wise and respectful to be judicious in requests for it.
1 Like
These are good points you listed. I really think aligning with the SOP standards would go a long way toward reducing the Qubes learning curve and would like to see this happen.
1 Like
Some basics knowledge should be set for writing a guide in this way, going with too much details would make it extremely long to write, and extremely boring to read for most users.
I mean, should it support basics like how to create a directory, editing a file or what is TCP?
1 Like