12

Some answers consist of a block of code (and maybe a picture) with little or no explanation. For example, I know I'm guilty of sometimes answering a "How do I do X?" question with "Here's one way," followed by code.

Do we want to encourage people writing answers to include explanations of what their code does? If so, is there a way to do so without giving an appearance of criticizing the answer or appearing unappreciative that the person took the time to write an answer? Or is it best to let the questioner ask for an explanation if one is needed?

9

We should encourage people to include explanations. Besides the questioner there are further readers, people come here via search engines with possibly a similar problem.

To avoid the impression of just criticizing: if we see the solution is good, the code works well, the problem seems to be solved - let's write it first in the comment. That's a good start for encouraging an improvement.

Here's a small example where I commented earlier today with this in mind: How to break a line in a table.

9

I would add a comment in the form of

great solution -- but I'm not sure how and why this works. Can you elaborate a bit?

  • 3
    That's what I'd do if it were in response to a question I asked and I didn't understand the answer. Frequently, I do understand the answers people provide to others' questions, but think that an explanation would make the answer better. – TH. Feb 26 '11 at 20:42
6

I would distinguish between two types of question here:

  • Questions answered with a variation of \usepackage{spam} or another well-documented solution (e.g. CTAN, TUG-UK, DANTE or what have you). In any case, a brief explanation should suffice, provided that a link to the e.g. package documentation or the authoritative solution is given. There is little incentive (or benefit, for that matter) for anyone to repeat what has already been done elsewhere, and probably explained better and in more detail.
  • Homegrown solutions: basically everything else. Here I'm talking about stuff like arcane TeX wizardry, specific bibliography request, creating special TikZ diagrams and so on. The answerer should be expected to provide more details on parts of the solution if/when requested, but that shouldn't extend to "go through the code and explain every line in a 5-sentence paragraph". I'd imagine that in most cases a brief explanation of the tricky part should suffice.

A somewhat tangential suggestion: new TeX users often find it challenging to contribute back to TeX-SE if they are not very well-versed in the typesetting system yet. I've seen at least a few users which were interested in participating, but were frustrated that they cannot even understand what some of the questions are about. Encouraging them to expand on a question that can be answered in a few lines, going from \usepackage{spam} and a CTAN link to producing a full (not necessarily minimum) working example will go a long way to retain them as regular users in the future. They will also build up some reputation this way, and as we all very well know, this is the perfect gateway drug into TeX-SE.

In this way TeX-SE could get both quick answers (usually by some of the old-timers), which are later elaborated into a more comprehensive example by users new to TeX for a long-term benefit. This could benefit old questions with already accepted answers as well.

  • I don't really agree with your answer on the \usepackage{spam} variant. Or maybe I do agree, but I'm not sure what you mean by "a brief explanation". I find that Caramdir's answer to one of my questions is an excellent example that mentioning a package + 1 line of code + an image makes a great answer. I do agree if this is what you mean by "a brief explanation". – Hendrik Vogt Feb 27 '11 at 15:32
  • @Hendrik: The answer you linked to is exactly what I meant. There's not much to add to an post like this anyway. Most of the time the user will just need pointing in the right direction, and can work out the details on their own. – Martin Tapankov Feb 27 '11 at 15:44
  • somehow we agree and disagree at the same time: I find that Caramdir gave me all the details. What I don't really like is just a pointer like "use the ... package", even if a link is included. The minimum I'd want to see is which command(s) to use, with an example how to use it (them). – Hendrik Vogt Feb 27 '11 at 20:59
4

Although I agree that explanations are really helpful, I worry about too much commenting by people other than the original questioner about explanations. Even when combined with a "nice answer" comment, asking an answerer to add an explanation might easily make people feel less inclined to post their next answer. This is especially the case when the posted answer is perceived as pretty self-explanatory.

Especially if the explanation is quite simple, it might be nicer to add the explanation with the "nice answer" comment itself, and maybe suggest to the answerer to add it to their answer.

  • What is perceived as pretty self-explanatory is in the eye of the beholder. And even when it's obvious to the answerer (and even possibly the OP) I still think it's worth having more explanation for beholders with less TeXnical eyes. – Seamus Feb 27 '11 at 12:06
  • @Seamus I compleletly agree with the usefulness of explanations; I'm concerned about comments that will be perceived as annoying, which may have the effect of driving people away. Because it's also the case that what counts as an adequate explanation is in the eye of the beholder too. – Alan Munn Feb 27 '11 at 13:03
  • I agree with the part "make a concrete suggestion of an explanation in the comment". – Hendrik Vogt Feb 27 '11 at 15:36

You must log in to answer this question.

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