What formatting recommendations do you have for posts?

Question

Bob Jones has noted that I edit a lot of posts and has asked me to post my style guide so I can be saved some work. Now, I don't mind editing, but that seems like a reasonable idea.

I'm not the only one who edits posts or posts well-formatted questions or answers on the site, though; what aesthetic recommendations do you have for posts? What are frequent formatting errors or typos, etc, do you see? What do you want people to know about formatting and cleaning up their own posts?

Answer 1

Fonts

For better or worse, there aren't too many choices when it comes to special fonts:

• Use italic style for transliterated words or for short phrases you wish to emphasize. Don't go crazy with long sentences or you will wear out your readers eyes/patience!

• Use boldface to really emphasize something. It works best when you want to draw your reader's attention to a particular point.

• Avoid bold italic unless you have a really good reason.

• Avoid typing in ALL CAPS, WHICH IS HARD TO READ AND SOUNDS LIKE YOU'RE SHOUTING. And please don't use bold italic all-caps!

• Don't worry about using Hebrew or Greek fonts unless you are already pretty comfortable with it already. Transliterations work just fine. I sometimes copy-n-paste from other sites if they are handy, but generally I don't bother.

Answer 2

This is an ad-hoc list. Much more could be said and I wish that less needed to be said (spelling and grammar...).

Content

• Pay attention to spelling, grammar, capitalization and punctuation! A browser with a spell-checker helps (yeah Firefox!).
• If you leave the verse numbers in a verse, superscript them with HTML tags (<sup>...</sup>).
• Hide raw links, i.e.:
  • This: ...is an example of the literary device anadiplosis...
  • or even this: ...is an example of the literary device anadiplosis (see the Wikipedia article)...
  • but certainly not this: ...is an example of the literary device anadiplosis (see: http://en.wikipedia.org/wiki/Anadiplosis)...
• Think about citing Bible versions. I try to cite the translation unless
  1. I have altered it ("the LORD" -> "Yahweh," etc)
  2. I did it myself (though I sometimes note that).
• For long posts, it is helpful to the reader if you break up your thought into chunks by using titles.
• This is slightly outside the scope of the question, but tag appropriately.

Nit-Picky

• Don't use regular hyphen when you ought to use a dash, if you can help it:

  • As punctuation in the middle of a sentence—like this—use em-dashes.
    (—, Unicode hex 2014/decimal 8212, HTML code —)
  • For designating number ranges (90–99% of the time on this site, it's used for verse numbers) use en-dashes.
    (–, Unicode hex 2013/decimal 8211, HTML code –)

• Unless you have a reason not to, spell out Bible book names rather than abbreviating, especially in the middle of a sentence. If you must abbreviated, use at least three or four letters.

Try to look at your post with a typesetter's eye. You want it to be attractive in a readable way (thankfully the site does not allow arbitrary coloring/fonts/sizes...).

Answer 3

Simple Tables

Sometimes tabular presentation of information is really what you want. Unfortunately, SE's Markdown doesn't (currently) support the table extension that many Markdown implementations include.

For simple tables, there is a nice solution:

1. Set out your data in your favourite spreadsheet program.
2. Copy it to clipboard.
3. Visit Senseful Solutions table generator -- also implemented at the ASCII Table Generator -- and paste into the "Input" field. (There is also a text-table generator at TablesGenerator.com.)
4. Select style option (either MySQL or Unicode art).* Click Create table.
5. Click inside the "Ouput" box, then CTRL+A, CTRL+C to select your nice shiny table.
6. Back at BH.SE, copy CTRL+V it into the answer, with <pre>...</pre> tags on either side. Done.

Demo: This is the kind of output you get (using a selection of plague traditions for illustration):

(1) MySQL:

     +---------+-----------+-------------+----------+---------+
     | Exodus  | Ps 77(78) | Ps 104(105) | Josephus |  Philo  |
+----+---------+-----------+-------------+----------+---------+
|  1 | blood   | blood     | dark        | blood    | blood   |
|  2 | frogs   | flies     | blood       | frogs    | frogs   |
|  3 | gnats   | frogs     | frogs       | lice     | gnats   |
|  4 | flies   | locusts   | flies       | beasts   | hail    |
|  5 | pests   | hail      | gnats       | disease  | locusts |
|  6 | boils   | pests     | hail        | pests    | dark    |
|  7 | hail    | death     | locusts     | hail     | boils   |
|  8 | locusts | x         | death       | dark     | flies   |
|  9 | dark    | x         | x           | locusts  | pests   |
| 10 | death   | x         | x           | death    | death   |
+----+---------+-----------+-------------+----------+---------+

(2) "Unicode art":

╔════╦═════════╦═══════════╦═════════════╦══════════╦═════════╗
║    ║ Exodus  ║ Ps 77(78) ║ Ps 104(105) ║ Josephus ║  Philo  ║
╠════╬═════════╬═══════════╬═════════════╬══════════╬═════════╣
║  1 ║ blood   ║ blood     ║ dark        ║ blood    ║ blood   ║
║  2 ║ frogs   ║ flies     ║ blood       ║ frogs    ║ frogs   ║
║  3 ║ gnats   ║ frogs     ║ frogs       ║ lice     ║ gnats   ║
║  4 ║ flies   ║ locusts   ║ flies       ║ beasts   ║ hail    ║
║  5 ║ pests   ║ hail      ║ gnats       ║ disease  ║ locusts ║
║  6 ║ boils   ║ pests     ║ hail        ║ pests    ║ dark    ║
║  7 ║ hail    ║ death     ║ locusts     ║ hail     ║ boils   ║
║  8 ║ locusts ║ x         ║ death       ║ dark     ║ flies   ║
║  9 ║ dark    ║ x         ║ x           ║ locusts  ║ pests   ║
║ 10 ║ death   ║ x         ║ x           ║ death    ║ death   ║
╚════╩═════════╩═══════════╩═════════════╩══════════╩═════════╝

Very handy!

---

^{* There is also HTML table output, but this is filtered out on SE. Maybe useful for other contexts, though.}

Answer 4

Sections, divisions and headings

Long answers tend to suffer from the wall-of-text problem. One solution is to write shorter answers, but that's not how we like things here on this site. A better solution is to divide your answer into sections. It's very common to include a Abstract, Summary, or Conclusion (but not TL;DR, please). These can be formatted as a heading by underlining with dashes (-):

Heading
-------

Or double-underlining with equal signs (=):

Heading (Bigger)
================

Lesser (or unnamed) divisions can be marked out with a horizontal rule:

----------

Another way to break up a block of text is to use lists, quotations, and (minimal) bold text. But if you are shifting from one discrete topic to another, it's best to use the sectioning tools.

Answer 5

Quotations

• Use > to begin a blockquote:

  > This is the beginning of a quotation.
  ^ It starts with the > symbol.

Note: Use blockquotes for quotes, not just to change the formatting of your own words. And remember to tell us where the quote is from.

• Avoid using the code block style:

      This is the first line of code.
  ^^^^Note that it starts with four (4) spaces.
  

• Sometimes you want to override the automatic word wrap. You can do that by:

  Starting a

  New paragraph

  or:

  Putting two spaces at the end of a line.
  (Two spaces over here:------------------>^^)

  (This tip applies everywhere, but is most helpful in the context of quoting things.)

• Poetry is hard to get formatted correctly since Markdown "eats" extra spaces. Your best bet is to use that code block:

  This is a bit of text that gets quoted before the start of:

  This poem is embedded in the blockquote,
     In a new paragraph with four leading spaces.
  

  You might also try   (non-breaking space):

  This poem is embedded in the blockquote,
    With two leading  .

Answer 6

Provide well-formed links

@Kazark already gave some good advice on forming links in an earlier post, but it is worth developing.

Please use meaningful text as the anchor for making links. Simply placing the link on the word "here" is not helpful, because:

• this obscures the character of the "target";
• it diminishes the value of the link; and
• if used multiple times, gets very confusing for those dependent on screen readers.

Consider this example (lightly adapted from a "real" answer):

See for example the chart here, or the examples discussed here or here.

A screen reader gets three "here"s -- but why should I click the links? The target in each case is an unidentifiable Google book, and it might be good, bad, or indifferent. The reader has no way to tell.

Better to provide at least some information as the anchor's link text:

See for example the chart provided by R.R. Ellis in Learning to Read Biblical Hebrew, or the examples discussed by William LaSor or, with more detail, by Korpel & Oesch.

At least now a reader knows the identity of the authors and, if the names are familiar, will possess some hints about the kind of material being provided. Even if the names are unknown, the link text is differentiated. There may be better text yet to provide, but this re-casting is fairly minimal yet makes a real difference.

For much more detail and expert advice on this matter, see Marieke McCloskey's article on Writing Hyperlinks, provided at the Nielsen Norman Group site (what was once useit.com).