Announcements ⇒ Avoidable Mistakes

[localghost]

… or: What makes a Post inadequate


Again and again there are postings which are considered inadequate by moderators as well as other users. Such requests are often hard to reply. Thereby potential helpers not only have to spend unnecessarily much time. These requests also result in frustration and demotivation on both sides and often cause long discussions. Particularly for beginners it is useful to know which deficiencies they should avoid. Other important things are mentioned in the Board Rules.

Inadequate postings or topics are such which have at least one of the following properties.

• The description of a problem does not contain a complete, self-contained and minimal example (also called a »minimal working example«, MWE) whereby everybody can reproduce the problem.
• An example is not a complete MWE but only an excerpt of code. The most frequent mistakes in this context are:
  • There is no preamble of the document given.
  • The preamble is left out.
  • The preamble is not minimalistic, which means that superfluous packages and definitions are not dropped by trial and error.
  • Packages are used which are not available for free.
  • The used packages are available for free but not listed on CTAN and there is no alternative source given.
  • There is only one main document given which reads external files. But these files are missing.
  • Further files like figures, bibliography databases or similar are necessary but these files are not provided.
  • The graphicx package is not included with the demo option or \includegraphics commands are not replaced with equivalent \rule commands of the same size.
• A given example is not a complete MWE because it is not anywhere near minimal. The most frequent mistakes in this context are:
  • Although external files loaded via \input or \include command could be inserted into the main file of the MWE, they are given separately and so complicate the process unnecessarily.
  • Although additional files could be provided inside a filecontents(*) environment in the main file of the MWE, this is omitted and so complicates the process. (Note: It is recommended to use the filecontents package.)
  • Instead of using one of the packages blindtext or lipsum, a MWE is furnished with masses of text.
  • The preamble is taken as is from the original document instead of reducing it by trial and error to parts that are relevant to the problem. Packages excepted from this rule are the following.

    Code: Select all

    \usepackage[T1]{fontenc}     % other or additional encodings might be suggestive
    \usepackage[utf8]{inputenc}  % Unciode encoding, other encodings possible
    \usepackage[english]{babel}  % other or additional languages possible, essential for documents not in English
    \usepackage{lmodern}         % only if other font packages are not substantial
    \usepackage{blindtext}       % alternatively the package »lipsum« is possible
    \usepackage{filecontents}    % only if externals files are unavoidable which can be provided in a »filecontents« environment.
    

  • The preamble contains additional settings and definitions which are not relevant and complicate to keep track of the problem. Where applicable they have to be removed by trial and error.
• The code is given as normal text instead of tagging it as code.
• There is a minimal example given and also a log file is provided. But these two things don't fit together because the log file is produced by another source.
• There is a minimal example and a description of the author's efforts, but there is no concrete question recognizable.
• The problem depends on a certain processing, i.e. the compilation with PDFLaTeX. But this information is missing in the description of the problem.
• Interfering options are used which need a certain processing, but this processing is not essential or not given in the problem description. Examples for such options are dvips, pdftex, dvipdfm or others.
• Commands or packages are used which are documented as obsolete, i. e. in the document l2tabu [1].

Although the above list appears very comprehensive, it doesn't seem to be exhaustive. Especially new members should attempt to follow at least these guidelines.

[1] View topic: Obsolete packages and document classes - Avoid usage!


____________
Credits go to M. Kohm from the KOMA Script Documentation Project.