20

Recently I answered a question that involved a fair bit of investigation on my part (link if you're interested).

The answer was about six lines long. Perfect.

But then I wanted to provide some supporting evidence for a statement I made, which turned into a long-winded step-by-step explanation that turned my nice short answer into a long wall of text.

I separated the main answer from the additional details with a horizontal rule:


But if anything, I think it made the post seem even more like an intimidating wall of text. So my question to Meta is this:

How do I provide additional detail without cluttering up the core answer?

14
  • 11
    As you already did partially. Use formatting and your writing skills to make a good and readable answer. A good explained, well written and well explained answer is always an upvote worth. Length doesn't matter, if it is a good answer it is good. (If you need "inspiration" how to format/word your answer, just read many other good answers, which I do too)
    – Rizier123
    Commented Aug 31, 2016 at 21:23
  • 1
    I agree with @Rizier123, although if you already have a blog or other site like that, you can post the more lengthy explanation there and link to it here. As long as the core of the answer exists here, more explanation on a blog works well. I've seen Jon Skeet (all praise he ;)) do this many times. Commented Aug 31, 2016 at 21:32
  • @MikeMcCaughan: Interesting point that I didn't consider. I always felt like linking my own blog would be on the narcissistic side (could be seen as a way to pump of visitor counts for ad money).
    – AndyG
    Commented Aug 31, 2016 at 21:43
  • 2
    @AndyG If it is your own site/blog you have to disclose that in the answer!
    – Rizier123
    Commented Aug 31, 2016 at 21:50
  • 1
    @AndyG As long as you are clear that it's your own blog (so as to not run afoul of the spam restrictions), I think it's a fine way of providing a "deep dive" on interesting answers. If I actually had anything interesting to say, I'd probably do it myself ;). Commented Aug 31, 2016 at 21:50
  • 5
    Putting information in an answer is not insulting. Commented Aug 31, 2016 at 22:00
  • @HansPassant: Forgive me if I'm parsing your syntax tree improperly, but I did not mean to imply that I was insulting the reader. Intimidating them or putting them off, perhaps.
    – AndyG
    Commented Aug 31, 2016 at 22:09
  • 5
    Your answer is great! Please don't leave out details like those -- some of us like to know why, especially if we have a similar-but-different question. Commented Aug 31, 2016 at 22:51
  • Thanks for the comments, everyone. Seems I thought it was a bigger problem than it is.
    – AndyG
    Commented Aug 31, 2016 at 23:11
  • 1
    @AndyG: Funny, there was just an answer to a similar question yesterday discussing exactly that, and it had at its worst 10 downvotes (now 9) which seemed to suggest that your concerns were completely valid.
    – BoltClock Mod
    Commented Sep 1, 2016 at 4:00
  • 1
    Your answer is fine I use this approach all the time. Not a fan of links though as they can go stale.
    – user692942
    Commented Sep 1, 2016 at 16:18
  • @BoltClock - I think the negative votes on there turned mostly on the factoring out (which sounds like "removing") content from SO. If you write a thorough answer and then want to add even more detail on your blog (and link to it), I don't think that'd be poorly received (so long as the answer can stand alone, obviously). But I think some people really choke on the idea of removing content from SO (even on your own post) in an attempt to drive traffic to your site. Once posted, the author has granted a license to SO... they don't have the right to remove content, even their own.
    – JDB
    Commented Sep 2, 2016 at 16:44
  • @JDB: And yet those who don't own the content have every right to vote it off as long as the content isn't their own. I don't know about you, but that sounds kind of insane to me.
    – BoltClock Mod
    Commented Sep 2, 2016 at 16:47
  • @BoltClock - If I saw a user remove a bunch of useful content from a post and replace it with a link to their blog, I'd flag it as vandalism (or I'd just rollback the edit). But yeah... it's one of those odd things. Once submitted, content is no longer under direct control of the author. It is voted on by the community, so the author can't delete it but the community can. Just ask Marvel about the Fantastic 4... rights and licensing gets weird fast.
    – JDB
    Commented Sep 2, 2016 at 16:51

1 Answer 1

17

Summary / In Short... / TL;DR

Use headings. Many scholarly articles and papers have an abstract or formal introduction that explains what was attempted and what the results were. State your most salient and action-oriented stuff up at the top, then go into full detail in the body.


The Introductory Paragraph

The common approach I've seen (and used) is to place a "Summary", "Introduction", "In Short...", "TL;DR" (or "Too Long; Didn't Read"), etc. section at the top with a brief summary of your answer. This might often include a very short block of code demonstrating how to achieve the desired result.

The introduction is a courtesy to the rushed developer when it's possible to abbreviate the solution, although some answers aren't going to be simple or abbreviate-able, so don't sweat it if you can't summarize at the top.

The Body

Sometimes the longer explanation is separated by an HR, especially when the summary is duplicated within the longer-form answer (for example: this post). When the body contains mostly alternatives or advice, however, then you'd usually just add additional headers for each relevant topic. You can add "long-winded" answers/alternatives complete with references, cross-references, statistics, step-by-step repros, images of unicorns (only if relevant) and a rabbit-trail on spaces vs tabs (spaces, obviously... but again, only if relevant).

Your Approach So Far

I think the approach you've taken is fine. HRs aren't the easiest thing to see, so a rushed developer may miss it or not realize that the content above the HR is duplicated in the content below. Section headings are helpful for breaking up content, making it easier to read and follow, so I'd generally recommend you use them in the future (if you care to).

What really matters in the end, though, is the content, and grateful engineers won't hold formatting against you if you remove an obstacle from their path.

How-To

Personally, I don't like my headings to stand out too much, so I usually use H3 formatting:

### H3 Heading

H3 Heading

If you want to further organize content, then I'd recommend using H2 formatting for your major sections and H3 formatting for your minor sections. You can even use bold formatting to break up content within a minor section.

## Major Section
### Minor Section
**Sub-Section**

Major Section

Minor Section

Sub-Section

I've occasionally seen posts complex enough to require H1 formatting to properly organize content, but usually I see this used for "shouting" or making a really, really strong point.

# H1 Formatting (and/or shouting)

H1 Formatting (and/or shouting)

You can feel free to use the headings however you want, though. It's your post and if you'd rather use the H1's then by all means do so. I'd much rather see a solution to my problem then beautifully formatted nonsense.

Examples

See some example in practice:

15
  • 5
    This is basically what he did already, except he didn't use the ignorant and insulting "TL;DR" label.
    – Cody Gray Mod
    Commented Sep 1, 2016 at 11:04
  • 18
    Sorry to ping you again @CodyGray, I'm just really curious if this is a commonly held opinion. Are you really insulted by "TL;DR"? Do you find it ignorant? I've never ever heard this opinion before and it's a bit shocking. What is your opinion based on? If this is considered improper then I'd stop using it, but the first linked example would seem to suggest that this is not a majority opinion... maybe I'm wrong though.
    – JDB
    Commented Sep 1, 2016 at 13:59
  • 11
    I love it when there's a TL;DR - it means I get to choose my level of effort
    – Jeutnarg
    Commented Sep 1, 2016 at 16:10
  • 11
    I also didn't know anyone found "TL;DR" insulting. I don't like its look so I usually use something like "Short Answer" or the like, but I don't find "TL;DR" insulting.
    – Suragch
    Commented Sep 1, 2016 at 16:12
  • To be fair to Cody, the first draft of my answer just recommended a "TL;DR". Since some people (at least three) find that insulting, I expanded the answer to include other alternatives.
    – JDB
    Commented Sep 1, 2016 at 16:13
  • 1
    @JDB It's flippant, which can be taken as insulting. It can also be interpreted as patronizing - that you think your audience is too dumb or lazy to read the full thing. (That said, I personally don't have an issue with it in relaxed web forums.)
    – R.M.
    Commented Sep 1, 2016 at 16:14
  • 1
    I think the best thing in your answer that would help out the readability of the OP's answer are the large text section headings.
    – Suragch
    Commented Sep 1, 2016 at 16:16
  • 4
    @R.M. - no, never too dumb. Some too busy for my pedantic wanderings, maybe, but that's on me not them. But if that's what comes across then is there a less insulting alternative? I hear that most researchers make a habit of reading only the first and last paragraph of a scholarly article (due to time constraints). Is there a preferred "Abstract"-type heading?
    – JDB
    Commented Sep 1, 2016 at 16:16
  • 7
    TLDRs are purely for people saying 'meh its too long, I don't care to read it'. It's not at all a statement about the reader's intelligence. It's a good way to direct your readers to the meat of your argument without needing all the premable. Commented Sep 1, 2016 at 16:17
  • 1
    As you have already used in your answer, a "Summary" or "Abstract" section header is the non-slang method of saying "TL;DR". "Summary"/"Abstract" does not carry any of the potentially negative connotations of "TL;DR". In fact, an "Abstract" section is normal for any published paper, while "Summary" is used more in business.
    – Makyen Mod
    Commented Sep 1, 2016 at 17:08
  • 2
    'too long don't read' is never insulting. Calling others 'ignorant' is.
    – TaW
    Commented Sep 1, 2016 at 17:35
  • 2
    Interestingly, I looked up TL;DR (en.wiktionary.org/wiki/TLDR) and got two definitions. The first dismisses a post as too long, and the second warns the reader that the remaining is long (the use proposed in this answer). Also interesting was the link to BLUF (en.wiktionary.org/wiki/BLUF#English). Perhaps this acronym should be used in contexts outside of the US military as it seems appropriate to this answer. Commented Sep 1, 2016 at 17:41
  • 1
    Thanks @JoshOfAllTrades - that at least explains the pejorative tone that some seem to read into that acronym. Odd that they'd find someone calling "TL;DR" on themselves insulting, though. Would probably be insulting if found in a comment, though.
    – JDB
    Commented Sep 1, 2016 at 17:44
  • 1
    @JDB: Thanks. I've taken your answer to heart and modified my post to include Short version/Long version sections
    – AndyG
    Commented Sep 1, 2016 at 18:14
  • @JoshOfAllTrades: yes if "TL;DR" is used standalone as a comment/response on someone else's post, or with a brief diss, that is pejorative. When it's self-applied by a poster to an abstract or summary of their own post, it clearly isn't. Other usages may not be e.g. "What is the TL;DR of your article please?"
    – smci
    Commented Oct 2, 2018 at 19:32

You must log in to answer this question.

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