6

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?

6

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.

6

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.:
  • 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 &mdash;)
    • 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 &ndash;)
  • 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...).

  • @BobJones here are a few starting pointers. I don't have time to post more now. Maybe I will post them as I run into them while editing. – Kazark Jul 7 '12 at 22:42
  • Thanks! How do you make Hebrew read backwards? Do you think that if blocks of scripture are quoted that verse numbers need superscripted? – Bob Jones Jul 7 '12 at 23:43
  • @BobJones It's my preference that they be superscripted or deleted; of course I don't make the rules around here. This is how I enter Hebrew; I'm actually amazed that you can make it show up the wrong way! – Kazark Jul 7 '12 at 23:46
  • 2
    @Kazark well, i believe i will let you continue to edit my posts on the nit-picky things. i'm a notorious book shortener and dash user. – swasheck Jul 8 '12 at 21:49
  • @Kazark your instructions for typing Hebrew are Greek to me ;-) I think you said I had to install fonts and change my keyboard. – Bob Jones Jul 9 '12 at 14:56
  • @BobJones Oh, that's right, you're not one of us computer geeks. Multilingual support is much better in Linux than Windows. If you are using Windows you won't be able to use my technique. – Kazark Jul 9 '12 at 15:14
  • @Kazark Well... years ago I had to punch machine code in binary... and then there was SNOBOL... ever heard of MUMPS? and not the puffy cheeks type ;-) – Bob Jones Jul 9 '12 at 16:56
  • @BobJones Wow, you just kicked my butt... – Kazark Jul 9 '12 at 16:58
  • 2
    @JonEricson How ironic that you would edit this post. ;) – Kazark Jul 10 '12 at 3:19
  • 2
    Beat me to the raw URL suggestion! – Jon Ericson Oct 1 '12 at 16:23
  • Slow clap... +1 – Dan Nov 29 '13 at 17:41
6

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.

  • 1
    This is definitely useful to know for those times when a table is the only reasonable way to display data. I would just note to be cautions of this if you have another option to layout your post because this does have drawbacks, especially for accessibility. For example it blows up on mobile as well as making life difficult in a couple other scenarios. Sometimes it will be worth the trade off, just know the benefit of desktop browser readability doesn't come completely free. – Caleb Feb 1 '14 at 22:16
  • @Caleb - exactly right. This was brought up in the first post (and most UV'ed) in that Meta thread I linked at the start. Apparently table Markdown is under consideration: that would deal with the mobile problem. Along with footnotes and "fenced" code-blocks, that would be my top three fervently desired Markdown enhancements! – Dɑvïd Feb 1 '14 at 22:26
5

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.

4

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 &nbsp; (non-breaking space):

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

3

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

  • Thank you @David. This is good. +1 – Kazark Mar 10 '14 at 22:57

You must log in to answer this question.

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