# What is an MWE?

A minimal working example (MWE) is a short test document that contains everything necessary to compile (e.g. `\documentclass{...}`, the necessary packages etc.) while still producing the error/problem you are asking about. 

# Some important points

- remember that we don't have access to your computer. Try to avoid images or included files in your MWE which we don't have. If you need things like images in your document etc to reproduce the problem, have a look at the files from packages like `mwe` or `duckuments`. These are included in most LaTeX installations

- try to avoid custom classes and packages if you can also reproduce the problem with standard classes and packages. If some custom class or package that is not available from ctan is essential to reproduce the problem, please post the source code of the class/package you are using to the question. 

- under certain circumstances it can make sense to add information on the TeX installation you are using. Sometimes packages have errors that got fixed in an update, so if you are using an older version others may have a hard time reproducing the error. (In principle a package update can also cause an issue that wasn't there previously.) Also the LaTeX kernel undergoes changes, so even if the packages are identical the outcome may differ depending on the kernel version.

- If you are using special fonts, right-to-left typesetting, special engines etc. check if you can also reproduce your problem without these things, this will increase the number of users who can try to help you.

- you might have concerns sharing you unpublished text on the internet. That is totally fine, we are not interested in the content of your document, probably most of can be removed in the creation of an MWE. If you need text to reproduce the problem, you can replace your own words with dummy text like lorem ipsum. There are several LaTeX packages that will help you with that, for example `duckuments`, `lipsum`, `blindtext` and [many more](https://ctan.org/topic/dummy-gen).

- "Is this a bad joke, my document is not working, how should I create a working example? If I were to know how to make it working, I would not be asking here" The name is probably a bit misleading, your document does not need to be working without error, but it should have all the necessary bits to work in theory if the error would not be there.

# Why should I add an MWE?

By adding an MWE you help both the people who try to help you and yourself

- An MWE is often essential to be able to solve a TeX problem. If you just describe the symptoms (for example "My document is suddenly in italic"), there might be many different causes and users can only guess what might or might not be the specific problem in your document. With an MWE the users trying to help you can see in your code what the problem really is.

- During the process of creating an MWE you will often be able to solve the problem yourself. Even though your problem is solved, please consider writing a questions and a self-answer if you think other users might face the same problem.

- Showing an MWE has the additional benefit that it often also shows your experience level in TeX. This might help users to tailor their answers to your needs.

- With an MWE you use the time of the users willing to help you efficiently. They don't have to spend time trying to reproduce your problem before even starting to work on a solution and you save them from the boring task of typing things like `\documentclass` for the 1000th time. In exchange this will cost you a bit more time, yes, but please remember that the other users invest their spare time for free when they try to help you, so it is a nice gesture to make it as easy as possible for them. It also helps to avoid unnecessary duplication of the work if multiple users try to help you and each of them would have to create their own MWE.

- With an MWE more people will be able help you because this combines the knowledge from the users willing to help you with yours. For example if you face a problem with some exotic package, then an MWE will show the other users how this package works and they can immediately start working on a solution for you. Without an MWE you are limited to either the users that already know your exotic package or are willing to spend some time learning it before even starting to work on an answer.

# How to create an MWE

There are at least two approaches

- Divide and conquer: Make a copy of your document and start to remove things unnecessary to reproduce the problem. A good strategy is bisecting: remove one half of the document and test if the problem is still there. If yes, repeat this step and remove half of the remaining document etc. If the error is gone, undo the last step and try to remove the other half. Repeat this until you have an MWE.

- Build from scratch: Create a simple test document that compiles without problems. Then start copying bits and pieces from your real document into the test document until your problem also appears in your test document. This should give a good idea where the problem comes from and you can again remove everything from your test document that is not necessary to reproduce the problem.

# Example

```
\documentclass{article}
\usepackage{graphicx}
\usepackage{lipsum} % to generate dummy text in this MWE

\begin{document}

\lipsum

\begin{figure}[htb]
 \centering
 \includegraphics{example-image-duck}% <- use some graphics that ship with the 
 \caption{A figure.} % usual TeX installations rather than some others won't have
\end{figure}
\end{document}
```

# MWE with bibliographies (MWEB)

In general the tips from https://topanswers.xyz/tex?q=606#a664 also apply to MWEs with bibliographies (MWEB). For many users it might seem harder to create an MWEB, because they often depend on external `.bib`. Therefore this answer will give some concrete examples differentiating between different bibliography tools.

While creating an MWEB remember to compile often enough (including running bibliography tools like bibtex/biber if applicable) because many changes will only take effect multiple compilations.

## `thebibliography` environment

This is the easiest case because no additional files are involved. 

```
\documentclass{article}

\begin{document}

text \cite{texbook} text

\begin{thebibliography}{9}
\bibitem{texbook} 
  Donald Ervin Knuth. 
  \textit{The \TeX book}. 
  Addison-Wesley, Reading, Massachusetts, 1983.
\end{thebibliography}

\end{document}
```

## BibTeX

### Sample `.bib` file

If the problem is not related to the content of the `.bib` file, most tex distributions come with several sample `.bib` files that can be used to demonstrate your problem. One possibility is `xampl.bib`[^*] :  

```
\documentclass{article}

\begin{document}

text \cite{book-full}
 
\bibliographystyle{unsrt}
\bibliography{xampl}

\end{document}
```

### Own `.bib` file

If the problem is connected to a specific bib entry, the users trying to help you will need to see this entry. To save them from having to manually create a new `.bib` file and copy the entry there, it is very helpful to use the `filecontents`[^**] environment that will automatically create a new file with the desired content.

```
\documentclass{article}

\begin{filecontents}{\jobname.bib}
@book{knuth:ct:a,
  author       = {Knuth, Donald E.},
  title        = {The {\TeX book}},
  year         = 1984,
  maintitle    = {Computers \& Typesetting},
  volume       = {A},
  publisher    = {Addison-Wesley},
}
\end{filecontents}

\begin{document}

text \cite{knuth:ct:a} text
 
\bibliographystyle{unsrt}
\bibliography{\jobname}

\end{document}
```

## Biblatex

### Sample `.bib` file

If the problem is not related to the content of the `.bib` file, one can use `biblatex-examples.bib` in the MWEB[^*]. This is a demo `.bib` file included in most latex installations which has examples for many different types of entries. 

```
\documentclass{article}

\usepackage{biblatex}
\addbibresource{biblatex-examples.bib}

\begin{document}

text \cite{knuth:ct:a} text

\printbibliography

\end{document}
```

### Own `.bib` file

If the problem is connected to a specific bib entry, the users trying to help you will need to see this entry. To save them from having to manually create a new `.bib` file and copy the entry there, it is very helpful to use the `filecontents`[^**] environment that will automatically create a new file with the desired content.

```
\documentclass{article}

\usepackage{biblatex}

\begin{filecontents}{\jobname.bib}
@book{knuth:ct:a,
  author       = {Knuth, Donald E.},
  title        = {The {\TeX book}},
  date         = 1984,
  maintitle    = {Computers \& Typesetting},
  volume       = {A},
  publisher    = {Addison-Wesley},
  location     = {Reading, Mass.},
  langid       = {english},
  langidopts   = {variant=american},
  sorttitle    = {Computers & Typesetting A},
  indexsorttitle= {The TeXbook},
  indextitle   = {\protect\TeX book, The},
  shorttitle   = {\TeX book},
}
\end{filecontents}

\addbibresource{\jobname.bib}

\begin{document}

text \cite{knuth:ct:a} text

\printbibliography

\end{document}
```

[^*]: In order to inspect the sample `.bib` one can use `kpsewhich <filename>.bib`, e.g. `kpsewhich biblatex-examples.bib`, from a command line to get the location of the file and then use your favourite editor to open it

[^**]: The `filecontents` environment doesn't overwrite existing files. The proposed filename `\jobname.bib` will result in a `.bib` file with the same base name as your main `.tex`.