Today I wanted to address a common issue I see in troubleshooting LaTeX errors, on StackOverflow and in personal questions. It usually stems from newbies who aren’t yet aware of all the functionality provided by standard packages and thus, try to reinvent the wheel when something doesn’t work the way they expect.

Why reinventing the wheel is a problem

In my experience, even from me helping people with packages that I’m not all that familiar with myself, it’s always best not to reinvent the wheel (even if you succeed, the result is likely sub-par unless you’re actually really good at what you’re doing).

Ask yourself if the functionality you want is something that’s likely to be a common problem. Then maybe somebody has already solved it in a comprehensive way! That’s what packages are for and that’s why they’re (hopefully) maintained by people who have given the problem at hand a good bit of thought. It is very likely that they have already encountered all the problems you ran into and have tried out all – or at the very least the most important – other possibly problematic consequences a certain solution might cause as a side-effect.

That said, I of course don’t want to kill your motivation to write your own LaTeX code. But maybe try something easy at first. Something of the degree of complexity that you fully understand all the commands involved and that has a clear goal. Once you’re experienced with that, you can go on to bigger challenges.

If you’re learning how to tweak code on an actual problem of yours, likely your judgement is clouded and you’re not approaching this with a clear mind and cool head like you should. But how to solve your problems then? Let me give you a step-by-step strategy how to.

A simple strategy for troubleshooting when a package isn’t doing what you want it to do

Step 1) Identifying the problem

I’ve seen many times when relative newbies – albeit confident and adventureous enough to tweak their LaTeX code to their own needs using info from the internet – have re-written commands to achieve functionality which is basically a part of the standard repertoire of the package they’re trying to use already.

And then they run into problems because they don’t fully understand what the package is doing or what the code that they found on the internet is doing. And how should they? It’s not a shame not to know everything yet – but…

Step 2) Find out the repertoire of the package you’re using (i.e. read/scan package documentation)

Before you run off to implement something yourself, please check first whether this might already be available as a functionality in a package and thus, you’re in danger of trying to reinvent the wheel. Not only is it a waste of time, it also often doesn’t end up working the way it should. Additionally, it usually complicates the code in a way that even someone trying to help you might be confused until they’ve brooded over your code for a long time.

Find out what your chosen package can and can’t do by consulting the package documentation which you can usually find by web-searching “latex + [insert package name]” or just go to CTAN. Also, it’s possible that while the package you were looking at really doesn’t implement the desired functionalitity, an alternative one does! Be sure to thoroughly web-search the issue until you’re sure that you have covered mostly everything.

When reading the documentation, make sure to read the first bit where there should be a usage example somewhere of the minimal working example of the package – or what commands to use so the package does it’s most simple and common functionality. You’ll need that for Step 3.

Step 3) Open a new document, make a Minimal Working Example for the basic behaviour of the package/command in question

Many times trying to help someone, I made a minimal working example of what they had given me – in order to first get a clear understanding what the package would do without any extra options or arguments. Most times, what the person was trying to do works out of the box after the clutter was removed! (Which probably came from seaching the internet for some code snippet which they thought might solve their problem – but it was actually the source of the problem in the first place because they didn’t fully understand the snippet of code which was likely meant to do something else entirely). This is no reason to be ashamed, it happens to me all the time that I don’t properly think my own problems through and rush to find help, only to realize that the functionality is available out-of-the-box anyway if you just make a proper MWE 😉

So now, do as I do when I’m asked to help with a package I don’t know: Make a minimal working example and try what you were trying to achieve in an uncluttered new document, in isolation (so that no other inference can happen, like conflicting packages and whatnot).

You can do the same thing on your own. Just open a new .tex document in your favourite editor (like Overleaf, for example), add the package you want using \usepackage{} and add one example of the code you wanted to make work. This is then called a ‘Minimal Working Example’ (because hopefully it works 😉 ). If you end up with the curious species of a Minimal Not-Working Example instead, fear not, at least this will let people know that you have tried and possibly, other people can quickly inform you what the problem was.

Step 3.5) If it doesn’t work, post your MWE on a tech troubleshooting platform of your choice, phrased in an understandable question with detailed info on what you’re trying to achieve, what you already tried and how it didn’t work like you wanted

If your code works now after trying the MWE, great – you’re so close to solving your problem. If not, at least you already have your ‘MWE’ (like it’s often called in internet slang lingo) that you can insert into your problem description which you give to a trusted LaTeX Ninja or post on StackExchange.

These things are helpful because that way,

a) one can try out the snippet in isolation to remove other causes of inferences and

b) other people can try out your code without you having to share your document with them.

c) Also, it makes it easier and less effort for people to help you.

And, let’s face it, everyone’s busy and usually, the people on platforms such as StackExchange and StackOverflow get annoyed when you make it hard for them (because why should they help you and go out of their way? They don’t even know you! Don’t make it hard for the nice people willing to help you!).

Step 4) If the MWE worked, remove or comment out the clutter in your old document and see if it works there too. If not, at least determine what kind of error you’re facing

If it still doesn’t work, try to isolate the problem more by commenting stuff out and reading the error messages. It’s hard to give a standard way-to-go from here.

But maybe you want to determine what type of problem you’re facing (on types programming errors see Algorithms, Variables, Debugging? Intro to Programming Concepts):

• Is it a syntax error? These are annoying but easiest to fix: Just read the error message, web-search how you might be using a command wrong and try to fix it.
• Is it a semantic error? That means that your document is compiling fine, your code is working but it doesn’t do what you wanted it to achieve. That means likely you’re misusing the package or command because you didn’t know or didn’t understand how it was programmed to work or intended to be used.

Step 4.5) The MWE works but that still doesn’t solve the problem that you don’t achieve what you wanted from the package

If the simplified version of your code (or your MWE) doesn’t do what you wanted it to do, look up in the package documentation if there’s a standard way to achieve this. If not, there might be an alternative package which includes this functionality.

If and and only if you’ve determined after careful research that what you want to do hasn’t been provided as a package yet, you may research how to code it yourself. But remember that most of the time, the package already does everything and it works unless you redefine some crucial stuff in an incorrect way!

And also, remember that simplicity always trumps complexity, especially if you’re a newbie and it’s not all that clear to you what you’re doing. In my process of learning more advanced LaTeX, I actually practiced rewriting code from other people because I felt the same (or a very close) result could be achieved with much simpler, more readable code.

I haven’t seen many problems where you’ll actually need more than 1-5 lines of code in LaTeX (of course, this pertains to problems which reasonably can be solved in an at least make-shift way by a newbie). Usually, once a problem is solved and you’re ready to simplify it and remove the clutter, the working end result is really not verbose. It’s short and concise.

If you’ve copied a 10+ line code snippet from the internet that you don’t fully understand, either consider not using it (if there’s any other alternative) or go through it step by step and understand what each line and each single command does. Haste is not your friend here. The problem might be super simple but you’ve already wasted hours by overcomplicating it!

I mean, yeah, maybe your 10+ line code snippet from the internet works, then great. But if it doesn’t, beware that you’ll likely waste more time getting it to work than solving your problem otherwise.

Step 5) If it really doesn’t work and you can’t find out how to make it work, ask on StackExchange

If you explain all the things you’ve tried out, what you’ve learned from your research, how you understand the problem or what the problem might be to your understanding and provide an MWE, people will be happy to help if they can. They just like it when you make it easy for them and show that you’ve tried to solve the problem on your own before turning to them.

Don’t reinvent the wheel. Try a Minimal Working Example instead. Honestly.

Best,

the Ninja

PS: Feel free to let me know if you’re stuck at some other part of the troubleshooting process that I didn’t provide a roadmap for.