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 :-)

The first sentence of this Style Guide says it's "a supplementary style guide", but it's not clear to me what it's supplemental to... w:Wikipedia:Manual_of_Style? Some other canonical style guide?

Yes, I think it's referring to the Wikipedia style guide, but I agree that "supplementary" is confusing. I support removing it from that sentence.

Unable to translate

@BenyElbis Hi, please explain what this means. https://www.mediawiki.org/wiki/Documentation/Style_guide shows a "Translate this page" link.

If I click on this link, I will determine the language I want to translate into, I will start translating. Unfortunately, this label is not on all the pages I came across

This page is already on "Translate this page"

I'm afraid I don't yet understand the exact problem. Can you provide a list of steps to reproduce, including links, step by step, and then what happens, and what you expect to happen? Thanks. :) (If it's easier in another language than English, feel also free not to write in English.)

Dobře píšu česky. :-)) Díval jsem se na to stránku https://www.mediawiki.org/wiki/Documentation/Style_guide a problém už je vyřešený. Chybělo tam tlačítko (nebo popisek) "Translate this page". Teď už tam je. Asi už to někdo opravil. Takových stránek jsem při překládání našel víc. Díky za spolupráci

@BenyElbis Ah, dekuju! Jo, to byl muj problem - mel jsem popisek tady. Ale je zvlastni, nerozumim co se tu stalo. :-/