I've just been asked to write a minimal example, what is that?

Question

I was posting some question about this strange thing LaTeX is doing when I try to compile my thesis. Someone asked me to provide a minimal example that reproduces the problem. My thesis is now a few hundred pages long and spans along ten different source files! How am I supposed to know what or where is the cause of the problem?

Do you have any hints or ideas on how should I go about producing such a small example?

Answer 1

Most questions about code are made more answerable by the addition of a minimal working example (MWE) or short, self-contained, correct example (SSCCE).

Your question may have an obvious answer, or it may not. You the questioner probably do not know the difference between the two! So think about it from the point of view of the answerer. To ensure that the answer she provides is sound, she will probably want to create a sample document, make the changes she recommends, and check that it works. If she thinks she knows the answer but doesn't have the time to create a sample document, she may in the interest of quality control refrain from answering at this time.

So make it easy for potential answerers! Give them a block of code that can be copied, pasted directly into a file, compiled, tweaked, corrected, and pasted back.

Here minimal means that the problem is isolated and there is nothing in the sample that distracts from the error you have or the effect you desire. Working doesn't mean the problem is solved :-), it means the code sample can be copied-and-pasted and directly compiled.

The site sscce.org is dedicated to the topic. There are also several articles on the topic as it applies specifically to LaTeX:

• “Creating a LaTeX Minimal Example” (PDF) from Dr. Nicola Talbot's LaTeX resources
• “How to make a ‘minimum example’” from the UK TeX FAQ
• “What is a minimal working example?” from the de.comp.text.tex newsgroup.

Errors

I didn't see your question, but I'm guessing that you got some error you haven't seen before, and said something to the effect of

I tried to compile, but I got the error `Undefined control sequence.' How can I fix it?

This is next to impossible to answer, unless you expect only answers from psychics.

Instead, look at the line numbers, and post that paragraph or sentence, depending on the scope of the error. You'll have to add any referenced packages or other components which are critical to the compilation of the section, but make it as focused as possible on the part which is the source of the error.

If there are no helpful line numbers, (make a backup and then) begin removing things you added after the last successful compile. If you remove everything you just added, perform a binary search by removing halves of the document until you can narrow it down. Then, post the section which caused the problem.

Often, this process will help you to discover the problem and solution yourself! If this happens, please still post your minimal example, add your solution as an answer, and accept it later. This way, future readers can benefit from your work (and you can get a self-learner badge if your solution was novel enough to get some upvotes!)

A better approach to the "I tried to compile..." example above would be something like:

I am trying to typeset the following equation:

\documentclass{article}  
\begin{document}  
Alpha particles (named after and denoted by the first letter in the
Greek alphabet,\[\alpha\]) consist of two protons and two neutrons bound
together.
This means that an \[\alfa\] particle is a helium nucleus. 
\end{document}  

But when I compile it with LaTeX I get this error message:

[22]
Undefined control sequence:
\alfa
`An \[\alfa\] particle is a helium nucleus.`

What am I doing wrong?

Enhancements

Other questions are not related to errors, but to a desired effect that the user wants to achieve, of the form:

I want to put (thing) at (place). How do I do that?

The MWE in this case should:

• be a full document including \documentclass, a preamble, \begin{document}, and \end{document}.
• include enough dummy text to make the document look like the one you're writing. The lipsum and blindtext packages are helpful here in that they provide macros to make lots of text without actually having to type lots of text.
• have your best-so-far implementation of the desired effect.

Try to keep your vocabulary accessible—do not assume that because many experts in your field use TeX that all TeX users are familiar with your field. A question about typesetting affine Dynkin diagrams will not get answered until you find someone who knows TeX and math.

If you have enough reputation to include images, please do. Images of both the desired effect (mocked up or copied from another document), and the result of your best-so-far implementation. If you do not have enough reputation to include images, upload to http://imgur.com/ anyway and post the links (an editor will include the images for you). If you do not have enough reputation to post links, enter the bare URLs.

Answer 2

This answer focuses more on minimalizing the code, rather than finding the source of the problem, as the top-voted answer does. It is intended to be concise and hands-on, but digestible rather than exhaustive. Suggestions for improvement welcome!

---

Here are some strategies for reducing your code, which will help you get better and faster answers, since it will be clearer what your problem is and the other users will see that you put some effort into producing a concise Minimal Working Example. Thanks for that!

Most likely, not all of these things will apply to your question, so just pick what does apply.

Document Class

－ Bad:

\documentclass{MyUniversitysThesisClass}

＋ Good:

\documentclass{article}

Using a non-standard document class? Does your problem still show up with article? Then use article.

Document Class Options

－ Bad:

\documentclass[12pt, a5paper, final, oneside, onecolumn]{article}

＋ Good:

\documentclass{article}

Using any options for your document class? Does your problem still show up without them? Then get rid of them.

Comments

－ Bad:

\usepackage{booktabs} % hübschere Tabllen, besseres Spacing
\usepackage{colortbl} % farbige Tabellenzellen
\usepackage{multirow} % mehrzeilige Zellen in Tabellen
\usepackage{subfloat} % Sub-Gleitumgebungen

＋ Good:

\usepackage{booktabs}
\usepackage{colortbl}
\usepackage{multirow}
\usepackage{subfloat}

You put comments in your code to remember what packages are there for? Great habit, but usually not necessary in a MWE – get rid of them.

Loading Packages

－ Bad:

\usepackage{a4wide}
\usepackage{amsmath, amsthm, amssymb}
\usepackage{url}
\usepackage[algoruled,vlined]{algorithm2e}
\usepackage{graphicx}
\usepackage[ngerman, american]{babel}
\usepackage{booktabs}
\usepackage{units}
\usepackage{makeidx}
  \makeindex  
\usepackage[usenames,dvipsnames]{color}
\usepackage{colortbl}
\usepackage{epstopdf}
\usepackage{rotating}

＋ Good:

% Assuming your problem is related e.g. to the rotation of a figure, you might need:
\usepackage{graphicx}
\usepackage{rotating}

You’ve developed an awesome template with lots of helpful packages? Does your problem still show up if you remove some or even most of them? Then get rid of those that aren’t necessary for reproducing the problem. (If you should later find out that another package is complicating the situation, you can always ask another question or edit the existing question.)

In most cases, even packages like inputenc or fontenc are not necessary in MWEs, even though they are essential for many non-English documents in “real” documents.

Images

－ Bad:

\includegraphics{graphs/dataset17b.pdf}

＋ Good:

\usepackage[demo]{graphicx}
....
\includegraphics{graphs/dataset17b.pdf}

＋ Good:

\usepackage{mwe} % just for dummy images
....
\includegraphics{example-image}

Your problem includes an image? Does your problem show up with any image? Then use the option demo for the package graphicx – this way, other users who don’t have your image file won’t get an error message because of that. If you prefer an actual image that you can rotate, stretch, etc., use the mwe package, which provides a number of dummy images, named e.g. example-image.

Text

－ Bad:

In \cite{cite:0}, it is shown that $\Delta \subset {U_{\mathcal{{D}}}}$. Hence 
Y. Q. Qian's characterization of conditionally uncountable elements was a 
milestone in constructive algebra. Now it has long been known that there exists 
an almost everywhere Clifford right-canonically pseudo-integrable, Clairaut 
subset \cite{cite:0}. The groundbreaking work of J. Davis on isomorphisms was a 
major advance. In future work, we plan to address questions of uniqueness as 
well as degeneracy. Thus in \cite{cite:0}, the main result was the 
classification of meromorphic, completely left-invariant systems.

＋ Good:

\usepackage{lipsum} % just for dummy text
...
\lipsum[1-3]

＋ Good:

Foo bar baz.

Need a few paragraphs of text to demonstrate your problem? Use a package that produces dummy text. Popular choices are lipsum (plain paragraphs) and blindtext (can produce entire documents with section titles, lists, and formulae).

Need just a tiny amount of text? Then keep it maximally simple; avoid formulae, italics, tables – anything that’s not essential to the problem. Popular choices for dummy words are foo, bar, and baz.

Bibliography Files

＋ Good:

\usepackage{filecontents}

\begin{filecontents}{\jobname.bib}
  @book{Knu86,
    author = {Knuth, Donald E.},
    year = {1986},
    title = {The \TeX book},
  }
\end{filecontents}

\bibliography{\jobname} % if you’re using BibTeX
\addbibresource{\jobname.bib} % if you’re using biblatex

Need a .bib file to reproduce your problem? Use a maximally simple entry embedded in a filecontents environment in the preamble. During the compilation, this will create a .bib file in the same directory as the .tex file, so users compiling your code only need to save one file by themselves.

Another option for biblatex would be to use the file biblatex-examples.bib, which should be installed with biblatex by default. You can find it in bibtex/bib/biblatex/.

Posting a Picture of Your Output

It’s often helpful to see what your current, faulty output looks like. If you’re not sure how to do that, have a look at How does one add a LaTeX output to a question/answer? and how can i upload an image to be included in a question or answer?.

---

_{Selection of packages inspired by Inconsistent rotations with \sidewaysfigure. Math ramble generated by Mathgen. Bibliography sample from lockstep’s question biblatex: Putting thin spaces between initials.}

Answer 3

Hopefully if your thesis is a few hundred pages long, you haven't been experiencing the problem you're asking about since you began it! If you were having the problem the whole time, then you could probably construct a minimal example basically by pretending to start a new thesis in the same way you started your existing one.

In the more likely scenario that you've just encountered a new problem, the best approach I've found is to start commenting out the newest pieces you've added one at a time and seeing when the problem goes away. At that point, you can try to make a new minimal document containing only the part you had to remove to make the problem go away -- if all goes well, you'll be able to make the new (much smaller) document reproduce the same problem.

It's actually not uncommon to end up finding the solution yourself when you start trying to construct a minimal example, but if that's not the case then once you have it you can add it to your original question to find help here.

Good luck!

Answer 4

Please note that the "minimal" in minimal working example means that the document should not contain any (yes any!) code which isn't related to the error. If a code line can be removed without changing the error/issue it doesn't belong into the example. If a non-standard class is used¹ for the original document and the error/issue still happens with a standard class then a standard class should be substituted. This means normally article or, if \chapter is required, report or book).

It is not required to use the minimal class for a minimal working example! In fact it should be avoided to prevent issues with missing definitions which are present in any real class.

¹ Standard classes are: article, book, report and letter.

Answer 5

There’s a new package on CTAN called mwe, providing some features for creating MWEs. This is the announcement text:

mwe provides several files useful to create a minimal working examples (MWEs). A mwe package is provided which loads a small set of often used packages for MWEs. In addition several different images are provided which will be installed in the TEXMF tree, so that they can be used in any (La)TeX document. This allows different users to easily share MWEs which include images commands without requiring to share image files or use replacement code.

See Martin’s announcement here on TeX.SX

Answer 6

Several TeX-specific pieces of advice exist. I'd start with the UK TeX FAQ: http://www.tex.ac.uk/cgi-bin/texfaq2html?label=minxampl

Answer 7

What is a minimal working example? is a work of some regulars of de.comp.text.tex. Here they describe in detail, how to produce a minimal working example.

Answer 8

Well, you can't just post your whole thesis and expect people to debug it for you...

It shouldn't be that hard to know which part of your thesis is causing the problem. Error messages should help you pinpoint which section of your LaTeX code is the problem - they usually include a file name and line number. You can then copy and paste it on here without any doubt that it will get solved.