I had some spare time this afternoon. And before wasting time in front of the TV, I did some research on our style guide. I looked at the Fedora magazine style guide we had discussed as a possible template, gathered some more recommendations I had developed myself in the course of my publishing work, and mixed it all together into a rough first draft.
I didn’t want to use hackmd.io again because the formatting is quite different. Instead, I put the text in our Contribution section without including it in the navigation. So it is not accessible via public links. But you can read the draft here
Maybe we can gather feedback here and make a decision at the next meeting.
How about including conversational style?
Due to differences in style among the Magazine, Quick Docs and Docs, we need to adjust the tone to fairly conversational for an audience of new users or least conversational for experienced users
Example: Less conversational style
Docs (like Server Documentation)
Where does Quick Docs fit in? I’d think it is fairly conversational criteria. In spite of being ‘quick’, Quick Docs needs to explain the instructions easier to follow through. It does not necessarily verbose for the sake of being more explanatory.
Good idea, yes! It’s a great way to break a complex and broad subject area into smaller parts while focusing the reader’s attention on a specific topic.
Hi @likeanushkaa! Good to hear / read from you. Yes, we should. In my 1st draft, I just couldn’t find our discussions about it in a hurry. And I trusted you to get back to us when you saw the draft.
By the way, I would like to have the combination of Tip, Important, Warning. But I think Tip and Note are functional equivalent. Or maybe green for notes? That might look more like “positive” and stand out more from all the blue on our pages. But maybe it doesn’t fit our color scheme design-wise?
And probably you might fill in your additional ideas? As it looks, we will soon have a development branch for the pages, and then we can work with PRs as usual.
Sorry for the late feedback, but here are my thoughts. I like it overall. I think we can start using this and add to it as we discover places where we’re being inconsistent.
We should link to the Red Hat Style Guide’s Usage dictionary and supplement it where needed. I imagine that it contains the correct style for most technical terms and upstream projects we’d need to reference, so there’s no need for us to reproduce it ourselves.
I’m not sure which section it should go into (or perhaps a new section), but we should require the use of references to other docs pages/modules instead of using the full URL
Since we don’t ship with a root account enabled, we shouldn’t need to use $ and # and should require all privileged commands to be run with sudo.
It’s not clear how we should refer to commands embedded in a sentence. For example, would it be “Use the clear command to clear your terminal output” or “Use the clear command to clear your terminal output”? I believe Magazine uses the latter, but so long as we’re consistent internally, I don’t think it matters too much.
We should add “verify links are valid” to the Processing tips
Before we go live with this, we’ll probably want to split the sections into separate pages just because of how long this will be.
Agreed. I can make an argument that tip and note are subtly different, but they’re close enough in terms of the actual impact that it doesn’t matter that much. I don’t have a strong opinion about whether we use “Note” or “Tip”. Whichever we choose, we should include guidelines for when to select which admonition in the Style Guide.
Even though it isn’t “enabled”, sudo -i will still get you there. Visually, I would prefer the single-character shorthand ($ or #) over seeing sudo repeated several times in a row. Also, as a sysadmin, if I do see a lot of commands that need to be run consecutively as root, I would run sudo -i once up front just to save myself from carpal tunnel. There are also a few ways that sudo xxx can bite you where sudo -i does not. A common one is with redirection (> or >>). Variable evaluation is another one. And I’ve also run into trouble when umask was set to 077 for the user – the global/system files that were created with sudo xxx ended up not being readable by the system users. I think sudo xxx is fine in some cases for the occasional one-off command. But I wouldn’t want to strictly require that it always be used. Especially in system administration documentation where basically every command needs to be run privileged and there are a lot of commands.
Just my 2¢.
Also, the Fedora Magazine documentation does currently state that sudo xxx should be used and not $ or #. But I think I would like to change that (I’ve sort of been ignoring that rule anyway).
And I want to clearly distinguish between user input and system response or message. Currently, we can’t use typographic means such as font size change, font change or similar. Hence, the more detailed and eye-catching labeling with […]#. And feedback on our server documentation found this style very helpful and clear.
I will incorporate the comments into the next version.
I’d be okay with using $ and #only in places where the reader can reasonably be expected to know that convention. I get that sudo -i permits a root shell and that many repeated "sudo"s looks bad, but we don’t want to confuse new and casual Linux users by using a non-default setup in our docs.
That makes sense. I’d also like to see Fedora’s documentation inform people of that convention. It is good for people to know that that # at the end of the prompt is a bit of a danger sign.
So, just to use a round number, how about a rule something along the lines of, “If the sequence of instructions on a page requires ten or more privileged commands, then instruct the user to use $ sudo -i first and place the following advisory inline in the documentation.”
Subsequent commands are being run from a privileged (“root”) shell as indicated by the # at the end of the command prompt. When finished, enter exit to return to your normal unprivileged shell.
Again, this is just my personal opinion of how I’d like to see the documentation styled.
Yes, it might be useful to link in every docs footer to a page describing the docs convention.
On the other hand, things should be as much as possible self-explanatory. The initial string “[…]#” resp." […]%$" provides, so my hope, enough context information that it makes the association with the command line on its own.
We should distinguish according to the intended reader. In a Server or CoreOS documentation, it is likely to seem strange. In IoT or Workstation documentation in may be informative.
And: Less is more. We should start with as few rules as possible and hope that they will be read and remembered. Depending on experience, we may then have to expand it.
I have a personal preference on how to organize the ideas when I write, I will break down what the rules I use seem to be here:
Always explain the concepts before moving on to examples
I personally prefer to know the “what” first, then the “why” and only then the “how”
Concepts should be explained just before they are used, if the same concept is used in several places, explain it as early as useful
this prevents re-explaining the same things over and over
If a concept is too complex, explain just as much as needed in a way that doesn’t leave room for wrong assumptions, then clarify certain aspects as they become needed
basically, don’t show all the complexity just at the beginning to not overwhelm the reader, don’t lie accidentally or purposefully to the reader, don’t make the reader learn things that they might not need or want to learn right now
If showing examples and having to show wrong examples, show the wrong example first then the right, explain why it’s wrong, which situations the problem might happen and, if this wrong case happens often, show lists of common examples
ideally the reader should understand why the example is wrong so they don’t repeat it and, if it happened by mistake, they will now understand where was the mistake
if something can do on a more general but unoptimized way and also on a more specific and optimized way, show and explaining first the general way and only then the optimized way; also explain the possible implicit assumptions in the optimized way
the optimized way might only work for specific cases, in case the optimized way won’t work, it’s better to understand the underlying rules so as to figure out how to make it work using the generic way
Things should always be true, even if technically true (as long as it doesn’t get in the way of understanding), technical terms first (if there’s not a better simple that conveys the full meaning) and, if it can’t be assumed that the reader will understand it, a quick explanation about the technical term that fits the goal and doesn’t leaves room for wrong assumptions
basically, correctness first, then usefulness
About way to write, I do like a lot Conversational style.
As long as I can also use the rules above, of course.
