Standards for editing

Question

I've being an active member of AskUbuntu and Unix & Linux for some time now. As such, I often edit Q&As. But I'm lost in some aspects and details of specific editing standards.

This post and this post are, in my opinion, just related, not duplicates (though there are parts that address my concerns), since these are not really answers, but suggestions.

1. Wall of text: posts of this type are for me unreadable. I think this happens to almost everyone. Should we separate walls of text into paragraphs to make posts more readable?

2. Paths/file names: should paths and file names be formatted as code?

3. Errors: code or block quotes? Is the length of the error a factor? My criterion would be: if it shows on the terminal screen, then it should be code.

4. Block quotes: when to use them?

5. Bold: why not use bold to highlight important text such as: "I'm using Ubuntu 19.10". For me this would make easier to grasp fundamental information in the posts, but it seems allowed just in the colloquial sense. Obviously not abusing it, just the right amount.

6. Links: should they be shown like "I followed this link" or like "I followed https://foo".

7. GUI paths: For example Preferences > Foo > foo. Should it be code, quotations, or something else? Does it matter if the separator is >, ->, → or something else?

This list may not be exhaustive. I navigate through it intuitively since I see sometimes contradictory edits.

I would like to have specific criteria for the editing process, to be consistent and ultimately helpful across my edits.

Or should I, once I've gained the reputation to edit freely in AU (as I have in U&L), just follow my instincts?

Answer 1

I want to focus first on one of your questions that I consider very important:

6. Links: should they be shown like "I followed this link" or like "I followed https://foo".

It is true that links that contain the title or other descriptive text about their destination (which, from context, is what I believe karel is advocating) are generally preferred to bare URLs.

But links that literally contain useless text like "this link" and "here" are not preferred in posts. That is bad for accessibility, as well as general readability. It takes relevant information away from the post, without replacing it with other relevant information. Not all ways of browsing the web facilitate efficiently checking the target of a URL.

Please note this is not just my opinion. Judging from votes on meta, we have a pretty strong consensus that edits should not change links from any other style into the no-information "this link" style. The major meta posts about this are:

• Mateo's answer to Should posts be edited to have readable links?
• A call to uphold accessibility by not shortening links to "here"

As a separate matter, when adding or changing a link one should ensure that the link actually (still) works.

(None of this is based on any recollection of any of your edits. These are problems that I've seen a lot lately in edit suggestions, in general.)

---

On your other questions, most of my thoughts are just my opinion. Here they are:

1. Yes, paragraph breaks can greatly improve readability. It is even occasionally helpful to break up a short paragraph into even shorter paragraphs. In particular, line breaks don't show up very well; in almost any situation where a line break is considered, a paragraph break is a better choice.

   But if a question consists of a single fairly short paragraph and makes sense, that's okay.

2. As karel says, paths are best formatted as code.

3. How errors should be formatted depends on the error, but like other text that is copied from a terminal, error messages copied from a terminal should be formatted as code unless there's a strong reason to do otherwise.

   Note that this is just a general statement. I think you may be wondering about my view of a particular post, but I don't know which post.

4. Blockquotes are good for quoting something that you want to format as one or more paragraph rather than a single short phrase. Besides web content and documentation, blockquotes are often a good way to quote messages shown by a program that do not appear in a terminal.

5. The way you've used bold in this meta question, for heading-like text that appears on the same line as other text, is good. I also think it is reasonable to use bold for emphasis, as I've sparingly done in this post.

   But names of software with or without a version number--like "Ubuntu 19.10"--should not be made bold. Even when someone has a problem with just one version of Ubuntu, or just one program, that version of Ubuntu or that program is still not more important than the description of the problem itself! And those names already stand out, due to their capitalization.

   On the very rare occasion that a post author's statement of what version or program they are using needs emphasis, I suppose I might consider making whole statement that they are using it bold. It still would not make sense for just the name and/or version number to be bold.

7. Personally I prefer the style Preferences → Foo → foo. This should not be formatted as code.

Or should I, once I've gained the reputation to edit freely in AU (as I have in U&L), just follow my instincts?

I wouldn't say you should just follow them, but yes, if I understand you correctly, you should follow them.

Meaning is what is important. Formatting and syntax are relevant to what a post means, and they can clarify or obscure meaning, but they do not determine meaning. Judgments about edits should involve considering what a post means and how the edit affects that meaning. This cannot be--or at least is not--encompassed by any existing formatting guidelines. So your own judgments--from reason, intuition, or a combination of the two--are of great importance.

Answer 2

1. Walls of text should be separated into paragraphs to make posts more readable.

2. Paths should be formatted as code. Example: /path/to/file

3. Errors should usually be formatted the same as code inside a code fence between start markdown ```none and end markdown ``` The none string at the beginning of the code fence markdown suppresses text highlighting which is visually distracting in an error message. Another way of formatting code is by selecting the code and clicking the { } button in the Ask Ubuntu editor. Formatting errors as block quotes doesn't make sense to me because they are text snippets copied from the terminal, the same as commands and code are.

4. Block quotes should be used for quoting excerpts of text, either for quoting text from a webpage or for quoting text from a question.

5. Bold text is frequently misused. The correct use of headers and bold text is for titles to organize text in into separate sections and categories. Bold text draws the eye towards the text which helps the reader to skip from one section to another.

6. There is rarely any point in showing an entire hyperlink. A less confusing way of formatting a link is in the more descriptive form of this example link: Repositories/CommandLine - Ubuntu Documentation. That tells the reader what the hyperlink links to without needing to click it.

7. Navigation in application windows is rarely enhanced by unnecessary use of bold text when italicized text would be less visually distracting, but using bold text is also permissible if it doesn't interfere with readability.