Encourage explanations

Question

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?

Answer 1

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.

Answer 2

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?

Answer 3

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.

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