Some TeX Developments

Coding in the TeX world

Asking for help

with 2 comments

I get quite a few e-mails asking for help with my packages, and also spot a few questions in various public places (comp.text.tex and The LaTeX Community, mainly). I’m always happy to help where I can, and it always makes my life a bit easier if the question arrives with all the information to start with.

One of the things that get repeated by almost everyone trying to help out users is the need for a minimal example. For LaTeX, that typically looks something like:

\documentclass{article} % Or perhaps memoir, beamer, ...
\usepackage{...}
\begin{document}
Example here
\end{document}

ConTeXt examples are not dissimilar, while plain TeX ones need very little at all (but I get very few of these). It’s much faster to supply everything to start with than to send a snippet with key details left out. It’s surprising how many things people simply assume are obvious, when they are not (“Surely everyone uses package wibble”).

Another useful thing to do in advance of sending a query is to send a log file. Again, LaTeX users are normally best advised to include \listfiles in their input, so the kernel makes a neat listing of everything in use (hopefully including the versions).

Often, I get description of either how things should look or why they are wrong, rather than an actual example. If at all possible, a “reference rendering” is much easier to follow. That can be something done in a drawing programme, using some alternative (but awkward) TeX code, or a screenshot of something. Describing things in words (especially if the questioner is not a native English speaker) can be a recipe for a long and painful process.

For questions posted in public, it’s always best to drop me a line so I spot it: I do my best but sometimes I miss things. For places such as comp.text.tex, that can simply be a CC on the posting, or for forums a quick note that says

Hello,

I posted a question about your <whatever> package:

http://some-url-here/

Please take a look.

will make sure that the issue gets me interest.

On the other hand, questions direct to me obviously get straight to the point but miss out on the public record part of a posting to Usenet. The same issues do tend to pop up more than once! Sometimes there is good reason for avoiding public postings: I get questions including unpublished material about achemso, for example. So I’d encourage anyone with an issue they think is general (such as a bug in one of my releases) to post something in public if possible. I always try to follow up postings as well as e-mailing people directly as well.

As I say, I’m always happy to try to help. I hope that most of the time I succeed.

Written by Joseph Wright

January 21st, 2010 at 8:28 pm

Posted in General

2 Responses to 'Asking for help'

Subscribe to comments with RSS or TrackBack to 'Asking for help'.

  1. Or you can juſt to refer to http://www.minimalbeispiel.de/ which has an even longer tutorial how to create a minimal example (both in engliſh and german).

    Dennis

    22 Jan 10 at 6:07 am

  2. It’s more the concept itself: I get quite a lot of e-mails purely of description with no TeX in them at all. That leaves me with the “crystal ball” approach to solving problems: not ideal!

    Joseph Wright

    22 Jan 10 at 8:29 am

Leave a Reply