The current guide is not a spiritual sermon aimed to teach anyone how to be a decent person, how to behave in society in general, and all that. Acceptable behaviour is already explained in community guidelines.
The superstar note is supposed to prevent unnecessary drama (as on a few recent occasions) due to the wrong assumption that once written, a guide becomes an untouchable holy scripture, deserving only loud-clapping feedback to not martyr a sensitive author (I am deliberately exaggerating to clarify a point).
While it sounds a little childish, i have no issue with the superstar note. I can imagine it may be more effective.
Your point is clear, and i agree that guide writers should be open for relevant corrections. This topic is specific about writing a guide, but those who give feedback should also be open for relevant corrections.
Off-topic & unacceptable behavior
Also not ideal when someone feels like a princes who enjoys criticizing inexperienced first time guide writers and don’t take the time to motivate her critics (cause busy, doing her nails). When someone tells her, maybe consider a more productive approach, she is not open for corrections and blames members (that are pro Qubes for years) to conspire against the project. She is so beautiful, self reflecting does not exist, a mirror exist only to look how pretty she is. (I am deliberately exaggerating to clarify a point).
Giving feedback that a guide is full with false claims and don’t take the time to motivate those false claims (only mentioning a harmless disagreement about intentional existing codes to lock a policy), is also not helpful. With other words, those who give feedback are also no superstars.
I like it, too, but it is a little bit idiomatic, so I think it is good to add the more direct “be humble”, just for those who are less familiar, or who use machine tranlators. I reckon “superstar” could get horribly mangled!
Such phrasing makes it an instruction - one that is impossible to follow. I don’t see the need for forceful moralization.
If you read the whole superstar section, you will see it is not telling anyone how to write. It is just reminding not to have unrealistic expectations.
In UK English, being humble and having humility are similar. But, in American language, being humble might mean speak as lower society people’s politeness to aristocrats or stay living in poverty. May be the word is more associated with “humble life”. Their explanation is hard for me to understand. But I have a habit of avoiding saying “be humble” to American people.
Good point, I have even succeeded in mystifying folk in the US, by using the ‘humble’ idiom. Some time ago, though.
Considering that, I might prefer something for the title that was even more direct, and less idiomatic, with more neutral tone. “Expect corrections” or sth.
That’s the end of that discussion, then. Point taken.
Seriously, I have no idea what kind of a “that’s all” you are meaning there.
It’s a difficult to interpret idiom…
Rhetorical question: Is it a “Now go away and shut up” one, or is it a “This is what I was really trying to say all along” one, or something else entirely? It doesn’t actually matter which: it just isn’t sufficiently clear and precise for me to understand properly. (Un)fortunately, I’m too stubborn and irritating to flounce off loudly and pretend to resign from the forum because of it.
A-propos: I think “precisely” might be a good addition to the first subheading: “Define the purpose clearly and precisely in the title” or similar.
For example, I find the “Hardened sys-firewall” example a bit less than satisfying. What is it hardened against? Is it using some special method? Is it the only possible type of Hardened sys-firewall, or does this guide cover all the possible approaches that could be given that name? Is there anyone for whom it would be “less hard” than the default? etc, etc. A bit more precision would be good, even if it makes the title a bit longer. Or do I have to read them all, just to decide if they are “Yet Another Minimal Debian Template” ones (which have their place, but are not what I am generally looking for.)
I agree. “Hardened sys-firewall” is vague to me and I’m more likely to miss if it has something useful to me. Practically, it has the same effect as clickbait titles on me. “Harden sys-firewall against [what]” sounds something I could classify without reading.
Seriously, I have no idea what kind of a “that’s all” you are meaning there. […]
I meant “That’s the whole idea of the superstar note”. I hope it is clearer now.
(Un)fortunately, I’m too stubborn and irritating to flounce off loudly and pretend to resign from the forum because of it.
Which is exactly the right attitude and what a serious person should do! - Whenever anything is unclear or confusing - ask, do not assume, and keep asking until it is completely resolved. Thank you for being an example of that!
Re. “precisely” - sounds reasonable but I am also (probably over)thinking:
Can something be clear without being precise? I.e. would “precisely” actually encourage the clarity or would it rather make the very first guideline overwhelming, thus probably discouraging to even read further?
Is it possible that “precisely” and “clearly” would conflict each other, e.g. when precision would result in a longer (and not concise) title, probably including unessential details, thus resulting in less clarity? How would one weigh which matters more in such potential dilemma?
I agree the “Hardened sys-firewall” is vague and made a suggestion for a change in an earlier reply. Let me know what you think. Feel free to suggest a better example.
I made some editions so that I resolved my previous points that were still valid:
I moved the introduction at the end of the guide, to a details section
2 new sections, with subsections: “how to write” / “how to contribute” because I think that most of the tips were about the writing process while some of them were more about how to act after the publication?
expanded the “duplication” section, to make the author consider editing and explaining duplicate guides + some steps can be linked instead of repeated (i.e. how to enable a service)
almost totally changed the “Must be Qubes-specific” section, I hope my example is okay.
a note/example on minimal templates in “You are writing for others”, with a link about the reasons why one should avoid minimal templates.
minimal examples in “Structure your document”
minimal code example + link to the official guidelines for writing command-line examples
I tried to stay concise, but if it not, please remove my additions.
While not addressing this directly, the guide is now telling the writer to do that.
Instead of the “superstar” section, why not something like that?
We call them “community” guides
Once you are sharing your guide here, it becomes a wiki post that everyone can edit. So this is not exactly “your” guide anymore. Be friendly to fellow community members and never forget you also learned from others.
Stay open to relevant corrections.
I haven’t clarified the fact that one could write a draft, etc.
That’s the end of that discussion, then. Point taken.