What is meta? ×
Meta Stack Exchange is where users like you discuss bugs, features, and support issues that affect the software powering all 131 Stack Exchange communities.

While I'm certain that I pay more attention to this than average, I still believe every user should, at least periodically, remember that judicious text formatting aids reading comprehension. And as we're all writers, this truly does apply to everyone.

Naturally, it can be misused and abused, too.

What formatting best practices do you follow? Any tips you wish could be presented to every new user? Is there anything that you see which should be used less?

share|improve this question

3 Answers 3

...This is how I like to format

I don't always obsess over formatting, but when I do...

Bold key phrases: I like it when readers can scan the post reading only bold text and still come away with the gist of it.

Italics for in-context emphasis: if I read a sentence aloud and find myself stressing a given word or phrase, then when writing it I'll italicize that. And now, I also italicize identifiers or language keywords when used outside of code blocks so as to avoid triggering the intentionally-ugly inline code style.

Superscript + subscript for footnotes: this simulates <small> (which isn't available on SO) and effectively de-emphasizes the text. And, don't use footnotes for critical information!

Headings to separate logical sections: H2 and H3 are ## and ### respectively in Markdown, and offer an effective way to make logically distinct portions of your text stand out. I don't recommend the use of H1 (#) or H4 (####) as the former stands out a bit too much, while the latter has no style at all.

Use lists sparingly: an ordered list can help when you want to emphasize order. An unordered list is handy when you have a number of distinct items that have something in common... but you intend to pack more than a single line of text into each item, you could just as well bold the start of each paragraph, or use sub-headings. If you do use a list of paragraphs, consider adding an empty line between each to help keep them from flowing together.

Use images to repeat what you've already said: your screenshot w/ hand-drawn circles and a simple drop shadow may not be worth 1K words, but it can help to drive home what you tried to say without requiring any additional words whatsoever.

capture of actual answer, not intended for demonstration purposes

share|improve this answer

Bolding important phrases, especially in longer paragraphs and posts, aids the scanability of the text, which is much more important in an online medium than in conventionally; moreso in a mildly-competitive forum such as SO. Additionally, I try to make reading those phrases in isolation (i.e. without the rest of the text) also sensible, and if it conveys the gist, then it feels like I've done a good job.

In particular for answers, the bold phrase will state the direct answer, while the rest of the text explains it. Or conversely, the direct or important piece of the question will be in bold. If you revisit the question with this in mind, did it help or hurt? Would removing all except the bold text be an improvement or make it worse? (Perhaps some of the major benefit from this process is how it shapes my own view of the answer to be more like someone else's?)

I feel italics should be used less frequently than bold, and I use them primarily for a change of tone where I wish to add character, or to emphasize a single word or short phrase that should not be read in isolation.

I wish click-here links were more often avoided. Not a huge problem (especially with the SO crowd compared to others, I believe), but using the domain, the full URL, or just parts from the URL is much better if you can't think of better link text.

Various real examples are in my SO answers, or read a few specific posts that prompted me to put this idea into words and get feedback.

share|improve this answer
2  
I showed several posters already, that their boldness is not as comprehensible as they wished it should. Why don't you just reduce your paragraphs to the content of the bold sentences, if they are the most important ones. That would increase readability! –  Ladybug Killer Jan 2 '10 at 16:05
    
Could you link to that? Or could you find some good examples you think would be better from my SO answers? (I know there are several, I try to keep the number of edits low.) –  Gnome Jan 2 '10 at 16:24
    
FWIW, I'd not have used bold in your comment, or used it around the whole phrase "boldness is not as comprehensible"; I think using it on individual words is a hindrance. (But always exceptions, stackoverflow.com/questions/1990932/two-main-functions-in-c-c/…) –  Gnome Jan 2 '10 at 16:26

I'm usually more of a fan of italics than bold - but that's just a personal preference. I reserve bold for rare cases where I'm not just emphasizing a word or phrase, but making absolutely sure no-one will miss it. Otherwise, I find that I'm drawn to bold text to the extent that it makes the rest of the sentence harder to read, which isn't a good thing.

Other than that, I think it's mostly common sense:

  • Use the preview pane - sure, it's not a perfect representation of what the finished post will look like, but it's a darned good start
  • Use lists where appropriate
  • Break large sections of text into paragraphs
  • Pay attention to spelling and grammar, not just formatting
  • Block quotes work well for quoted text (duh) although they can be tricky in terms of formatting within the quote. (I usually have to experiment to get a list within a block quote, for example.)
  • Format code appropriately - few things look sillier than code which has been cut and paste without indenting; import statements (etc) end up all squashed together as text, followed by code which was naturally indented anyway
  • Format inline code, particularly if you're referring to type names or variables from full snippets
  • I've found that footnotes in the form of a superscript number in the text, a horizontal rule after the text, and then the footnote itself, works well on occasion

I think anyone who actually takes a bit of care over the general appearance and readability of their posts is unlikely to have a problem - and those who don't care aren't likely to change due to advice, unfortunately :(

share|improve this answer
    
Yes, I focused on bold and italics perhaps a bit too much. One bit about inline code: I've noticed a tendency to not format names (mod_ule::name, Module.Name, var_iable), but still format expressions (even nearly the same as names: Module.Name(blah)). –  Gnome Jan 2 '10 at 17:51
1  
I tend to still format variable names as otherwise they can mess up comprehension - particularly if they're just English words. –  Jon Skeet Jan 2 '10 at 18:45
1  
Formatting all variable names usually would improve clarity if the code markup would be a bit less intrusive. As it is now, it easily makes the post look ugly (meta.stackexchange.com/questions/33709/the-rivers-are-rolling), so formatting all variable names has fallen a bit out of fashion. –  sth Jan 2 '10 at 21:06
1  
@sth: I take your point, but I prefer "ugly but clear" to "pretty but confusing". There's also the hope that the formatting may be improved at a later date, at which point all the existing posts will become more pleasant :) –  Jon Skeet Jan 2 '10 at 22:21
    
preview should be quite close to actual now –  Jeff Atwood Jan 4 '10 at 5:05

You must log in to answer this question.