1. In a nutshell

A minimal example is a .lyx file that is as small as possible while still showing the behavior that you are asking about. It should include as few dependencies as possible – remove any unnecessary pictures and external files. It should be possible for someone to download your .lyx file and without modification see the same behavior that you are seeing.

Below is more information on how and why to create minimal examples.

2. Why create a minimal example?

In general, the work of active open source community members (developers or engaged users) is like a simultaneous exhibition game: you address them with a single problem which is very essential to your own work, but they are themselves addressed by many other people at the same time. So if you ask them to just try and reproduce the problem themselves, it might not strike you too much to be asked, the more so as the problem seems obvious to you. But from the point of the community member, first, the problem might not be obvious at all, and second, any extra time they invest accumulates strongly given the multiple request they get. And please also remember that LyX is driven by volunteers only. The time people invest to help you is taken from their personal leisure time, their coffee and lunch breaks, their family time. So please help as much as you possibly can in order to get help.

In short:

Minimal examples make it easier for people to see the problem you are talking about and thus easier for them to propose solutions.
They save time. If five people download your .lyx file trying to help and spend 5 minutes removing the graphics you included and cleaning the LaTeX preamble that is not necessary, then that's 25 minutes of wasted time instead of the 5 minutes that you could spend doing that. By sending a minimal example, you can make it as easy as possible for someone to help you. Thus, more people will get motivated to look into the issue and help you solving it.
They take time. How is this a good thing? If you show that you are willing to spend time to solve your own problem, this makes it more likely that someone else will want to spend his/her time to help you with your problem.
Often, once you've removed everything extraneous, the root cause becomes obvious and the problem solves itself.
While continually removing material in the making of your minimal example, you might run across material that toggles the symptom off when removed, and toggles it back on when put back. Once you get that toggling material down to a few lines, the root cause often becomes obvious, either to you or to those you're asking for help.

3. How to create a minimal example

Remove as much as possible from your .lyx file while still making sure it shows the behavior you are reporting.
- The preamble (top menu bar Document→Settings...→LaTeX Preamble) should not have anything except what's needed to reproduce the bug (further, it's helpful if you specify that without something in the preamble the problem in question goes away).
- Document settings should not have anything special unless it's needed to reproduce the bug:
  - If you can reproduce the behavior by using the document class Article (Standard Class) instead of a less common document class, please do so.
  - Remove any modules (Document→Settings...→Modules) that arent't necessary to reproduce the problem. If a module is necessary to reproduce the problem, please explicitly state that! If it is a module not included in the LyX distribution, you need to attach it to your report.
  - In Document→Settings..., set all settings to the default. If a setting is needed to reproduce the problem, mention that in your report!
- There should be no ERT (explicit TeX code) in the example unless absolutely necessary to reproduce the bug (in which case say this explicitly).
With large documents, the bisect strategy is often useful to reduce the document rather effectively:
1. Cut off half of your document
2. Check if the error persists.
3. If yes continue from 1
4. If not, add the cut part again; cut the other half and continue from 2

Do this until you have reduced the document to the one thing that triggers your problem.

If the example requires external files (graphics etc.), make sure they're included in your email or trac bug report.
Use relative paths if you need to include external files. Further, relative paths should work when all files are put in the same folder. That is, ../../Dropbox/MyLyXstuff/picture.jpg is relative but bad; ./picture.jpg is relative and good.
Test your minimal example. Just before you send it, copy the example files to a different folder. See if things compile fine. Make sure that the output still shows the problem you're seeing.

4. In addition to a minimal example

It is useful if you attach more files in addition to the example, such as your pdf output (or your log from your attempt to produce a PDF output). Sometimes it's not obvious if the output shows the problem or not (e.g. if it requires a foreign language that the person trying to help does not know how to read). Similarly, it is useful to provide the .tex file that you export from LyX. This is useful in particular to see if a difference in PDF is due to different LyX versions or different versions of TeX files. For similar reasons, it is useful if you provide the corresponding .log file.
If your question is about LyX's display (and not PDF output), then please provide screenshots.
It is always a good idea to specify your OS (and its version) and your LyX version (where you got the binary from or whether you compiled LyX yourselves).

5. Minimal example FAQ

5.1 But the error happens for every document. Why should I post an example?

Many of the reasons here still apply (e.g., to make it perfectly clear what you're talking about, to save the person helping you time, and to show that you're willing to spend time to make and post the example). Further, it is possible that a new document for you is different from a new document for me. The reason for this could be different versions in LyX, or you could have (possibly accidentally) clicked on the "Save as Document Defaults" button, which saves your current document settings as the template for when you create a new document.

5.2 Whenever I remove something, my problem goes away. What should I do?

Knowing that you cannot reduce your .lyx file is useful information. It not only gives information about the possible bug that you are seeing but it also shows that you made an effort.

5.3 What if my `.lyx` file contains material that I don't want made public?

After removing as much as you can, if your .lyx file still contains private information, state in your email if you would be willing to send this file privately. Usually, however, it's possible to anonymize your minimal example.

5.4 How do I post a .lyx file on a forum or a Q&A post without attachments (e.g., tex.stackexchange.com)?

Although some forums allow you to attach files, some encourage text-only posts (and possibly images). In this case, it is important to recognize that a .lyx file is just a text file. You can insert the file by opening it in a text editor, copying the entire contents, and pasting as text into your post. Please format the text as "code" or something similar. This way, the viewer can copy your pasted "code", paste into an empty text file, and then open the file with LyX.
The above method of "attaching" a .lyx file is preferred to putting a URL to a third-party site where the file was uploaded (e.g. Dropbox), because forums like to preserve posts as long as possible so others with similar problems can see the entire post; and often, links to third-party uploads break over time.

5.5 What are other relevant resources for a minimal example?

LyX MWE on tex.se

FAQ

<< | FAQ.PageList | >>

MinimalExample