15
\$\begingroup\$

I understand editing questions for clarity, but is there a style guide somewhere for Questions and Answers, detailing things like "These things should be italic, these should be bolded, capitalized these powers but not these in references, etc."?

I'd like to have some reference so that I can format my text in a manner that requires less editing.

\$\endgroup\$
27
\$\begingroup\$

We don't have a local style guide. There are a few common practices that we inherit from a few different sources though:

  • Because we are using HTML (which is a format designed to be both human- and machine-readable), which gives specific meanings to certain kinds of markup, we benefit from recognising HTML semantics: italics for emphasis, bold for keywords and technical terms.

    (All-caps is, online, widely considered to be SHOUTING. It's never necessary to shout for emphasis!)

  • We benefit from following general English style expectations: italics for Book and Movie Titles, quotation marks around “Song Names” and “words-used-as-words”. (Most often double quote marks, because single quote marks stand out less, visually. But this is a matter of personal taste and isn't generally edited.)

    That said, italicising every mention of RPG books can sometimes feel really unnecessary, so often RPG book titles get no special formatting here. From experience that's fine — rarely is it unclear what's meant when the italics are left off.

  • RPG style has some influence: for example, it is common for D&D to use either title case for the Names of Magic Items and of Spells or italics for the names of magic items and of spells.

    (This varies by D&D edition though, so you'll see people disagreeing about this. Generally, this shouldn't be changed through editing, because both are correct and switching the style doesn't make a post even a little bit easier to read. This is similar to AmE and BrE spellings: it's not appropriate to edit someone's spelling of “realise” to “realize” or vice versa, since it wasn't spelled wrong in the first place. As a rule of thumb, we try to be consistent with the original author's spells and spelling conventions when doing an edit.

    Specifically this edit to your question is probably what inspired your meta question. It was unnecessary and did not actually help the post at all, and you shouldn't take it as a sign that there is anything wrong with the style you had already been using. If you wanted to, it would be appropriate to reverse the edit's changes.)

  • Inline code formatting should never be used for emphasis, highlighting, technical terms, or quoting. Its HTML-defined meaning is “this is input to a computer”, and we have italics for emphasis, bold for highlighting and technical terms, and quotation marks for quoting, so no need to misuse code formatting.

    (The exception is tables, which we will often fake using non-inline code-block formatting to make the table columns align.) There used to be an exception for tables, but since it was made available we can use MathJax to lay out tables.

    We do occasionally have posts that mention literal computer input in their paragraphs, and inline code formatting is appropriate for those. We save it for that use.

  • Because it's standard English practice and how our formatting system is set up, large blocks of quotation go in blockquote formatting, which means starting each paragraph of the quote with a > character.

  • Book/page citation style varies in English and is only defined by various academic style manuals, so we don't naturally inherit anything in particular. Go with whatever is familiar, clear, and has a verbosity or brevity that suits the particular position of the citation.

  • It helps sometimes to divide a post into sections with headers. Never use bold for these section titles! Such “fake” headers are invisible to machine-reading and can seriously impair our site's accessibility to people who use assistance programs. Instead, use the header formatting options provided to create semantic section headers. They will look better in a visual browser, too.

    People will sometimes use horizontal lines to break up sections of a post too, when a separate title for the section doesn't make sense. It's easy to overuse them, but sometimes the judicious use of a horizontal rule makes a significant improvement in how the post reads.

  • Our list formatting input is unfortunately American-centric in its design: it doesn't recognise 1) or 1.) style lists (yet!), so list numbers always have to be written 1. like that, followed by a period. Otherwise, they don't render into into an HTML list at all.

In practical terms, what these influences combine and add up to, in terms of a “common denominator” of how to format a post and have it be understood and not look “random” is:

  • When in doubt, less is more so just leave out a piece of inline formatting when you're unsure about it.
  • Standard emphasis is to use italics.
  • Put proper nouns in Title Case, in general, especially if there is a need to make it clear that they are a Name and not just words.
  • Powers are often proper nouns (but not always), so Title Case is often used and works fine. Sometimes it's desired to make them stand out though, and in that case use keyword formatting to make it clear it's a special term.
  • Technical terms, similarly, often don't need any formatting, but when they do need to be formatted so that they're unambiguously seen as a technical term, use technical term formatting.
  • Use double quotation marks by default. Single will sometimes be useful though.
  • Use Markdown's formatting features for outside-of-paragraph formatting whenever possible, to give a post visible and semantic structure that matches the structure of its existing intended meaning.

This looks like a big pile of rules, but what I wrote at the beginning is still true: we don't have a local style guide. We have various influences — English writing conventions, our Markdown formatting system's design, HTML's structural semantics, the styles that appear in RPG books and academic citation guides — that people are familiar with or that the human and machine consumers of our pages expect, so looking at those helps figure out good style practices. Seeking the lowest common denominator of all the styles that our readers understand is the most effective way to format a post.

In the end, clarity is the foremost concern, so what's clear and unambiguous is always best. And when a post is already clear, it shouldn't be edited just to make it different without any clarity improvement.

\$\endgroup\$
  • 1
    \$\begingroup\$ Also, I never thought of #. as an American style or #) as a non-American style; I certainly see both used frequently in America. \$\endgroup\$ – KRyan Jul 13 '16 at 19:11
6
\$\begingroup\$

I'm going to come at this from a slightly different direction, addressing the writing style rather than the presentation style...

Answer the question quickly and obviously.

There's a lot that goes into some of these answers. But I think the best style advice I've seen and gotten was to "front-load" an answer post with your answer itself. Follow that with all your wonderful explanations, developments, examples, &c.

For everything else I'll second SSD's excellent answer. There's much good advice in there. (And you'll notice that he follows this advice--look back at his first sentence!)

\$\endgroup\$
  • \$\begingroup\$ This could use a bit more detail. As someone who tends to write novels, here's what I've learned: 1. Make sure you answer the question asked. Many an otherwise-good answer, clearly containing the info the querent sought, has been marred by failing to correspond to the wording of the question as asked, forcing you to read the whole thing before you can figure out what their position is. If it's a yes/no question, start with yes or no! 2. Start at the end. When you're wrapping up with "in conclusion" or "TL;DR - ", go back and put that at the top in big letters. \$\endgroup\$ – SirTechSpec Jun 26 '16 at 3:23
  • \$\begingroup\$ 3. Make it easy to skim. This is less important if you have the gift of keeping your answers under a paragraph (which I clearly lack). If you're writing something long, instead of a big block of text, use the lists, headings, blockquotes, and other stuff d7 explained to add whitespace where appropriate. Bonus points if you begin each paragraph or list entry with a bolded summary of the point of that paragraph, as I've done here. It's far from mandatory, but much easier to tell one post from another if you can effectively see an outline of the post by looking at headers and bolded text. \$\endgroup\$ – SirTechSpec Jun 26 '16 at 3:34
  • \$\begingroup\$ 4. Slightly tongue-in-cheek at this point, but don't answer in comments. Besides being against core site policy and having a length limit, most formatting doesn't work. \$\endgroup\$ – SirTechSpec Jun 26 '16 at 3:38
  • 4
    \$\begingroup\$ These are all good points, STS--perhaps should be their own post? I'd upvote it. I imagine over time this question's answers turning into a collection of best-practices, not just one answer to rule them all. And the post that combines your 4 points (plus 5 and 6, which I'm sure you'l think of while writing) would make a good addition =) \$\endgroup\$ – nitsua60 Jun 26 '16 at 3:45
  • \$\begingroup\$ Yeah, in my mind this was just a quick suggested edit to your answer, but we can see how that turned out. :P I'll write 'em up. \$\endgroup\$ – SirTechSpec Jun 26 '16 at 3:48
  • 1
    \$\begingroup\$ Done. I surprised myself by not thinking of any more points today :) \$\endgroup\$ – SirTechSpec Jun 26 '16 at 4:13
5
\$\begingroup\$

I think d7 covered the major points, but building off what nitsua60 said about answering quickly, here are some thoughts on how to present your answers (both in terms of writing style and formatting) so they're easier to read:

  1. Make sure you answer the question asked. Many an otherwise-good answer, clearly containing the info the querent sought, has been marred by failing to correspond to the wording of the question as actually asked, forcing you to read the whole thing before you can figure out what the answer's position is. If it's a yes/no question, start with yes or no!
  2. Start at the end. When you're wrapping up with "in conclusion" or "TL;DR - ", go back and put that at the top, probably in a heading. (Think of it as the section heading for your entire answer.) This is a good time to check #1 as well.
  3. Make it easy to skim. If you're writing something long, instead of a big block of undifferentiated text, use the lists, headings, blockquotes, and other stuff d7 explained to add whitespace where appropriate. Bonus points if you begin each paragraph or list entry with a bolded summary of the point of that entry, as I've done here.

    It's far from mandatory, but it is much easier to tell one post from another, find particular points to reference or rebut, etc. if you can effectively see an outline of the post by looking at just the headers and bolded text. (This is less important if you have the gift of keeping your answers under a paragraph, which I definitely lack.)

  4. No RPG.se styleguide would be complete without mentioning probably our most-broken rule: don't answer in comments. Besides being against core site policy and having a length limit, most formatting doesn't work.
\$\endgroup\$
  • 2
    \$\begingroup\$ #4 isn't style guide material, it's just site rules and breaking it is how to get your comment deleted. similar goes for #1. \$\endgroup\$ – doppelgreener Jun 26 '16 at 10:02
  • \$\begingroup\$ @doppelgreener 4 maybe, but not 1, at least not as I meant it. I'm not talking about unrelated rants, I'm talking about helpful answers that do answer the question if you read them, and so get upvoted, but aren't optimally clear due to phrasing. Happens all the time without deletion. \$\endgroup\$ – SirTechSpec Jun 26 '16 at 12:54
  • 3
    \$\begingroup\$ Then #1 would be better if it were rephrased to make that clearer. You aren't talking about not answering the question. You're talking about making the answer obviously stand out \$\endgroup\$ – Wibbs Jun 26 '16 at 14:41

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .