Topic on Talk:Documentation/Style guide

One of the most complicated sections is the table in Documentation/Style guide#Formatting Text. There is widespread variation in external style guides, and inconsistent usages throughout our own documentation, especially in user-oriented docs vs developer-oriented docs.

I've attempted an overhaul, using this 2018 diff and the older 2015 diff that we started with, plus consulting the HTML spec and some of the external style guide examples.

I'm hesitant about some of the changes, and hope to discuss the pros/cons some more with you all. If you know of any exemplary in-current-use examples to aid in that discussion, that would be great. Aiming to be "descriptive not prescriptive", as much as possible.

I wonder if it would be better to move that content to a subpage where we could be a bit more verbose and less constrained by the table format and just leave a really short set of examples on the main page. For the main page content I'm thinking more of a definition list like:

Code

short strings of code, including wikitext markup

Syntax highlight

.citation { margin: 0; }

...

Re: location and length: Hmm, maybe. I'm reluctant to split out, because subpages tend to lead to content-forking and fewer page-watchers. However I do like the idea of trying different options.

Re: complexity: I'm more concerned/unsure about what specific formatting we want to recommend for each use-case. E.g.

• The 2 diffs (linked above) had completely different recommendations for when to use bold/italic/monospace. Which of those 2 describes the way we currently do things? Is there any pattern/consistency between the hundreds of existing pages? Do we want to change any of the existing practices to a new&better standard pattern?
• Do we ever really want to recommend <kbd> ? - it's barely detectable as a monospace font, depending on the surrounding text...
• The very informal/imperfect method (commonly used in talkpages or IRC) is to just use "quotes" for everything that needs to be highlighted/distinguished from the surrounding text. It's sometimes used in documentation pages, and I'm often uncertain what to replace it with, or whether there are technically appropriate usages. E.g. the current diff of help:formatting has a few. I suspect this is related to the <kbd> question.

Sorry, I'm late to the game on this one! I'd argue for including additional rules that make practical sense to this section and allowing for a variety of ways to format certain kinds of text and information.

If we find that most pages are or aren't following a guidelines or using completely different ones not documented here, we should revise the guide to fit the most common practices. I would personally fall on the side of the easiest, most commonly accepted and privilege those as preferred in the guide -- which I would argues is more a common set of best practices rather than a perfect standard.

I know that this might seem contrary to the idea of a guide or guidelines or rules, but we are working together on wikis with many contributors from many different backgrounds of varying abilities and skillsets. The goal here is not perfection but clear understanding :-) We can do our best by outlining best practices (but we may find there is a better or more common practice).

@Quiddity and others Thank you for making changes and additions to the formatting standards :-)