Community Guides: How to write a useful guide

Community Guides
1

The purpose of a guide is to share knowledge and teach others. Approach it as responsibly as you would teach your own beloved ones.

Before posting the guide

Clearly define the purpose in the title

The title must be:

  • meaningful (matching content)
  • concise (single line)
  • readable (no emoticons/text decorations or word stuffing, check spelling)

Good:

  • Improving LibreOffice GUI performance
  • Hardened sys-firewall: additional IPv6 protection
  • Minimal Kicksecure template

Bad:

  • Awesome ultra-secure perfect anonymity for everyone. :warning: Start using 𝖓𝖔𝖜:warning: (clickbait)
  • Network setup (too generic)
  • Ultimate networking (misleading)

Avoid unnecessary duplication

Before starting a new guide, check what similar guides or docs already exist, it might be better to edit them. If yours really offers anything different, that is very welcome. Repeating what is already known would hardly be helpful though. When you bring something different, link your guide and the existing one(s) and provide a short summary of how they differ.

If your guide contains a step already described somewhere else, consider linking to the other documentation instead.

Good:

Before proceeding to next step, you must enable a service.

Bad:

Here is how to enable a service: [followed by retelling of what is already documented…].

Must be Qubes-specific

Good:

A guide that shows how to rsync between two qubes.

Bad:

A guide that shows how to use rsync in a single qube. (which can be done on any GNU/Linux system)

If your guide is about something very specific, using only the official Qubes tools, consider contributing to the official docs instead of the “external documentation”.

On AI usage

If you use AI, disclose that in initial line of your guide.

You are writing for others

Some people have less experience and knowledge. If relevant, remind what preliminary knowledge may be necessary. If your guide relies on minimal templates, make sure to include an appropriate warning.

Do not mislead

Always clarify the threat model in security guides.
Never claim a solution is final or ultimate.

Accessibility

Avoid using images without explaining what is on them. Visually impaired community members won’t be able to read that.

Structure your document

  • A flat wall of text is much more difficult to read than properly structured text sections.
  • Do not overuse styling - those who use the forum through text-only mail clients may not be able to see all the fancy formatting. Always rely on content, not on formatting alone. E.g., headings should be only used for structure, not to get a bigger text.
  • Links are fine, link farming is not.
  • Visually separate code and command-line sections, making them readable and separating them from explanations:
    qvm-move FILE.txt
    See here for more examples
  • Longer documents can benefit a table of content at the end of the guide.

Code and formatting

  • All code and content must be free. Unless other free license is explicitly mentioned, The Unlicense will be assumed.

  • If your guide includes code, make sure it is properly formatted and readable.

  • If the code is hosted/versioned on an external website, take care to explain what it does when linking to it.

  • Code per se is not a guide. To make it part of a guide, please include proper additional comments.

Follow the official documentation guidelines

The Qubes OS documentation uses a different markup, but it has some additional guidelines that might be useful.

After posting the guide

Be ready to provide support

Don’t just post and leave. Stick around - others may have questions and suggestions.

A clear and specific question deserves a clear and specific answer.

If the question is unclear, ask for rectification. Yet, if it undoubtedly reveals additional learning is necessary, kindly provide terse advice without going off-topic.

You are not a superstar

This is not a personal show or an entertainment.

Sharing knowledge is at the core of this community and our guidelines apply to everyone. Be friendly, keep your feet on the ground, and never forget you also learned from others.

Stay open to relevant corrections.

Notify when necessary

Post proper updates whenever you edit important parts of the guide. Those who use the forum by mail may not know when certain post is edited.

Comments and suggestions are welcome.

Original context

After some recent discussions, it seems a good idea to have something like this. Please let’s keep this civil and useful for the community.

Disclaimer: I am only opening this thread. Anyone should be able to suggest improvements and edits based on further discussion.

14 Likes
2

Does a relevant correction include the use of labels such as ‘false claims’ and ‘theater’ when dealing solely with differing cybersecurity philosophies that present no actual, direct risks? In my opinion, using labels like ‘false claims’ and ‘security theater’ hinders productive discussion. In cybersecurity, different viewpoints and approaches routinely exist regarding risks and practices. When there is a matter of differing perspectives, rather than factual inaccuracies or real risks, we should phrase our feedback in a way that invites dialogue rather than discouraging the writer.

3 Likes
3

I’m willing to enhance this guide but I know I won’t do that right now, so some comments instead:

  • the bad examples could be explained
  • it is fine to somehow duplicate a guide if there is a clear explanation of their differences at the beginning of the guides?
  • must-be Qubes specific should be expanded (ie: if everything takes place in only one qube, it might have nothing to do with Qubes OS)
  • the “superstar” part isn’t clear enough, maybe we should also tell that it is fine to ask some questions, to work on a draft, etc. before publishing ?
  • the image part could be linked to my own guide about that
  • structure and code formatting could benefit from examples
  • also we should tell the writer that it is possible to create a table of content
  • I would like to add a part about what belongs to the forum and what would be better in the official docs
  • some other advice from the official docs could be useful here
  • a note on not promoting minimal templates?
4 Likes
4

I believe a section regarding the offering of criticism should be added.

I suggest the following wording:
If you wish to offer criticism, please ensure that it is constructive, objective, and presented in a friendly manner. Remember that this community consists of real people, so please keep that in mind. We also ask that you express your point of view clearly

I also suggest improving the reporting section; specifically, the reasons for submitting a report should be clarified, focusing exclusively on factors related to social proof.
For example:
(You should submit a report if you suspect that the content involves:)
The deliberate dissemination of misleading information.
Failure to disclose the use of artificial intelligence in instances where it has actually been employed.

It was also suggested to include a quote from the Code of Conduct, for example:

This is a Civilized Place for Public Discussion

Please treat this discussion forum with the same respect you would a public park. We, too, are a shared community resource — a place to share skills, knowledge and interests through ongoing conversation.

Improve the Discussion

Help us make this a great place for discussion by always working to improve the discussion in some way, however small. If you are not sure your post adds to the conversation, think over what you want to say and try again later.

Be civil. Don’t post anything that a reasonable person would consider offensive, abusive, or hate speech.

Using welcoming and inclusive language

Being respectful of differing viewpoints and experiences

Gracefully accepting constructive criticism

Focusing on what is best for the community

Showing empathy towards other community members

A Note on Trust

Expect all contributions to be reviewed with some amount of healthy adversarial skepticism, regardless of your perceived standing in the community. This is a security project

Quoted from : guidelines, Code of conduct

(My phrasing might not be entirely precise, but I hope the idea is clear; if not, I would be happy to provide further clarification.)

4 Likes
5

Yes, as long as those judgements are substantiated. Both ‘labels’ are commonly used phrases in security literature and functional analysis. (And they mark things, that are far from ‘philosophical digressions’ AFAIK.)

See:

How would you go about classifying an ‘indirect risk’ in comparison to a ‘direct risk’?

2 Likes
6

Even without forbidden words, we keep reading complaints about “censorship”, so I think everyone should feel free to express oneself within the limits of acceptable behaviour as per forum terms.

As for factual inaccuracy, I don’t see how such can be justified by anyone’s perspective. Example:

“It is safe to open any file downloaded from website X, so download this binary and install it in your template.” (someone’s personal perspective/approach and a false claim creating a security risk)

3 Likes
7

@parulin

I’m willing to enhance this guide but I know I won’t do that right now, so some comments instead:

  • the bad examples could be explained

Or maybe replace them with some more self-explanatory? (like the first one)

My idea is to keep the guide as short and concentrated as possible - easier to read and comprehend. An extensive one might be discouraging, no?

  • it is fine to somehow duplicate a guide if there is a clear explanation of their differences at the beginning of the guides?

Sounds reasonable.

Maybe we should also suggest the writer to credit properly other’s work, if one is used?

  • must-be Qubes specific should be expanded (ie: if everything takes place in only one qube, it might have nothing to do with Qubes OS)

Yes, but also things like /rw/config/rc.local or extra template minimization (which needs to consider Qubes package dependencies) are Qubes-specific.

  • the superstar part isn’t clear enough, maybe we should also tell that it is fine to ask some questions, to work on a draft, etc. before publishing ?

What do you mean? That one first starts a guide and then learns what should be in it? I am not sure I understand.

  • the image part could be linked to my own guide about that

Please do.

  • structure and code formatting could benefit from examples

That sounds challenging. Too broad, too many languages…
What do you suggest?

  • also we should tell the writer that it is possible to create a table of content

I don’t know how this will work for mail. Currently some posts that include extensive HTML formatting appear as a mess of tags and text in text-only clients. Maybe we can test it?

  • I would like to add a part about what belongs to the forum and what would be better in the official docs

Please do.

  • some other advice from the official docs could be useful here

Please do.

  • a note on not promoting minimal templates?

Why?

1 Like
8

That is the core of my argument. Nothing against those labels when they are substantiated. At least motivated or proved.

How do secure operating systems tell the difference between urgent emergency patches and non-emergency patches?

1 Like
9

There is no censorship on this forum. Please know that I value your contributions and this isn’t a personal attack on anyone. This is purely about improving the quality of our debate and keeping the atmosphere productive.

1 Like
10

As far as I know, there is no difference. ‘Emergency’ is a time-based category, not a cause-based one. Therefore, it’s not a matter of whether things get fixed, but how much testing time there is. In the context of QubesOS, risk mainly concerns isolation breaches and DOS scenarios. Once something is found to be wrong, it gets fixed. Even if it was only an ‘indirect’ part of an exploit chain.

I was interested in the definition of direct vs. indirect risk because, in my opinion, once you abandon ‘indirect risks’ as ‘less important’, things like user error, misbehaviour and wrong assumptions are ignored to a certain degree as well. However, the user is one of the main targets of attack if statistics are correct.

“Does a relevant correction include the use of labels such as ‘false claims’ and ‘theater’ when dealing solely with differing cybersecurity philosophies that present no actual, direct risks?”

That’s why I’d like to ask again: Where do you draw the line between ‘direct risk’ and ‘indirect risk’?

2 Likes
11

I agree with your opinion. It’s not about abandoning ‘less important’ issues. All risks should always be addressed. It’s a matter of tone. A harder approach makes sense for clear errors in a guide, but minor disagreements should be handled more constructively to keep the thread productive, ultimately resulting in all risks being addressed.

In my opinion, a direct risk is when a guide contains an immediate actual error that instantly degrades the system’s active security/privacy state. An indirect risk is when it only reshapes the environment, introducing the potential for future technical and behavioral failures but does not necessarily create a direct vulnerability.

4 Likes
12

Thank you. It would be valuable to integrate something like that so that everyone can understand.

3 Likes
13

I added a few words and removed one of the good examples (which is actually not good).

@michael - thanks for the corrections.

2 Likes
14

The few words are perfect. Not sure if the good examples are very good: there are multiple ways to achieve a “hardened sys-firewall”, so few words to tell the reader what is used to do so might help.

By putting this HTML code at the end of the post, you create a TOC (I just made this change to the current guide, as an example:

<div data-theme-toc="true"> </div>

I hope it is only a minor annoyance in mailing list mode.

2 Likes
15

Looks great and not an annoyance at all. I didn’t even know a TOC could be added this way.

Maybe “Hardened sys-firewall for DNS restriction”? Or an entirely new example?

4 Likes
16

Maybe “Write with humility” instead of “You are not a superstar”?

I think it fits better with your other parts and the general Qubes OS tone.

And maybe change the whole block i quoted to:

Write with humility

The goal is collective contribution, not individual spotlighting.

Stay open to relevant corrections. See feedback as a way to improve your guide, not a personal attack.

3 Likes
17

Just to add to this: Improving the guidelines above is great, but is the real issue not that people aren’t reading the documentations in the first place?

Maybe we should also focus more on that? Just a first idea, but what if we add a pop-up when someone tags ‘community guide’? Something like: ‘I’ve read the guidelines and understand the responsibilities it brings. If not, read … carefully.’

First-time guide writers might get overwhelmed by the comments. I think when we require a quick confirmation beforehand, it would help manage expectations.

2 Likes
18

Humility and modesty are not qualities anyone can express intentionally. If you know you are humble, you already have an image of yourself as of some wonderful human being - a superstar.

That note is aimed to remind that guides are but mini technical docs.

I thought about the same. Perhaps after there is sufficient agreement on a particular version, mods can pin this thread and possibly place proper notices.

3 Likes
19

What about both ?

“Write with humility - you are not a superstar”

It is good to keep our feet on the ground!

2 Likes
20

I spend a lot of time re-writing technical docs because a user misunderstood something I thought was clear.

Very often, their logic was perfect, but their viewpoint and background were not ones I had thought of - so the problem was with me, not them.

It is very humbling to explain or describe things to a diverse audience.

2 Likes