# Best practice on definitions: description vs paragraph and others

I would like to define some technical terms (e.g. precision, repeatability, error, accuracy, ...). I have seen tutorials doing it in two different ways:

\begin{description}
\item[term] describing text
\end{description}


or

\paragraph{term}
describing text


What are the differences and which way is suited for what application and might there be an even better option?

## 2 Answers

The description environment conceptually is an itemize-like environment, so a "list", used to list some items, enhancing their names and displaying their descriptions so that they are separated and indented from the normal text (hence enhanced), and more clearly visible.

\paragraph is a sectioning command, thus indicating a division in your document, which can usually be used to insert some notes, or some small paragraphs which talk briefly about a specific topic. The spacing between the word(s) that start the paragraph (i.e. the ones between the braces) is bigger than the one used in description. Mind that for long descriptions, these flow like the normal text and are not displayed in an indented environment.

I would go with description, which is more compact and enhances the definitions, and usually never use the paragraph environment, unless there are some remarks about the text above them that I want to attract the reader to.

EDIT

I'm adding an example

\documentclass{article}
\begin{document}

\begin{description}
\item[item1:] a somewhat long long description about your item and all about it and look how pretty it is displayed like this
\item[item2:] a somewhat long long description about your item and all about it and look how pretty it is displayed like this
\end{description}

\paragraph{item1} a somewhat long long description about your item and all about it and look how pretty it is displayed like this

\paragraph{item2} a somewhat long long description about your item and all about it and look how pretty it is displayed like this
\end{document}


• What about page breaking (favoring inside or inbetween item-breaking), page filling and referencing behavior?
– n4pK
Apr 6, 2017 at 7:00
• @n4pk I'm not an expert on page breaking, I think that both commands are prone to between-item breaking. About referencing it depends: paragraph are, I think, more easily referenced, but you have to number them... If you have that much amount of terms, maybe you're interested in creating a glossary? Apr 6, 2017 at 7:10
• You can keep the semantics of a description list and customize the format if you don't like the default LaTeX format. Look at the enumitem package. Apr 6, 2017 at 9:23

I tested description and paragraph a bit myself and realized, that in general description should be used. Here is a small comparison:

• As seen in Moriambars answer: description indents all the trailing text lines, whereas paragraph only has indentation for the first line.
• description fits better between leading and trailing text. For paragraph it is hard to see, whether the trailing text is part of the description or not. (So you may use paragraph only, if your whole section is about definitions.)
• The descriptors for descriptioncan NOT line-break; paragraph titles can.
• paragraph entries may (obviously) end up in the table of contents (if tocdepth is set accordingly)
• You can not reference the descriptor name (as far as I know), only the page or the section, in which the description is included; but you can nameref the paragraph.

I experience once, that all the description items tried desperately to fill the page, creating large white spaces in between them. Here is was not able to reproduce this behavior.

Here is the MWE:

\documentclass[a5paper]{article}
\usepackage[pass]{geometry}
\usepackage{hyperref}
\usepackage[nameinlink]{cleveref}
\usepackage[english]{babel}
\begin{document}
\setcounter{tocdepth}{5}
\tableofcontents\newpage
\section{Definitions with the \texttt{description} environment} \label{sec:sec1}
Here is just some text to fill up some space in the front, to make the document look like some common tex example. I need to continue to write senseless text, so the space will be taken from the page.

\begin{description}
\item[item 1:\label{des:item1}]Just a little short text here.
\item[super-duper-very-extra-mega-long item which doesn't line-break] Obviously \texttt{description}-descriptors can not line break... Very sad.
\item[s.i.:] Here comes a very short item, but it should also have a reasonably long describing text.
\item[item four] Just some random text, which should take up some space right behind the item-element.
\item Here one example without a descriptor.\\ Can we have manual line-breaks inside the description? Oh yes, we can!\\ I remember some case, were there was strange spacing between list-items, trying to fill up the page.

But apparently it does not occur in this case.
\item[last item] Let's see one more item in the list.
%\item[last last item] There is always a last \texttt{item}.
\end{description}

Juuuust a little more text to fill a line after all the describing stuff above. And another line allmost filled! The line is not filled yet, so I have to write some more. And more... AND MOOOORE!! So much text! This is an incredibly long text, where latex has no place to simply page-break it. Let's see how it performs.

\section{Definitions with the \texttt{paragraph} instruction}
Just an introductional text-line.

\paragraph[apparently paragraphed items may end up in the table of contents]{Paragraphed item 1}\label{par:item1}
I am tired of inventing text. \texttt{Blindtext}, help me out here! Ohh.... no blindtext... Damn. Now I have to fill the text again by myself! Ooooh byyyy myyyyy seeeeelft. Don't wanna be... Ah. Were you singing along?
%\blindtext

\paragraph{super-duper-extra-mega-very-very-extremely-long item which does line-break}
A somewhat very longer description.
\paragraph{} Lets have an empty one, just as we had before. Just to see how it looks. How about manual line-breaking?\\Mom, can I touch it? Only if you wash your hands afterwards!
\paragraph{s.o.:} or a short one!

Does this text belong to the last item? Who knows? Nobody does! You just can't really tell. Too bad. It almost looked good.
\section{Referencing (with \texttt{cleveref})}
\cref{des:item1} on \cpageref{des:item1}. Does not work properly... \texttt{nameref} crashes.\\
\cref{par:item1}, \nameref{par:item1} on \cpageref{par:item1}. Does also not work perfectly. But at least \texttt{nameref} works.
\end{document}