Why should you avoid using (complex) templates?

Question

^{This question is intended to be something reference-like to point users of complex templates they do not fully understand to.}

After having read What is a template? it should be clear what a template is. Many questions here deal with rather complex templates (e.g. for thesis writing) and users ask how to modify a specific template. Often they are suggested not to use the template at all, but write up a document from scratch.

Why should users avoid using those complex templates or, if you see it the other way around, when should templates be used?

Answer 1

I'm a user. I have no idea of TeX, plus neither of Lua nor of »expl3«.

I'm a user. I made an installation of texlive or MikTeX on my computer. I read an introduction to LaTeX and learned about some basic packages as well as about what an editor is, why encoding is necessary and about babel / polyglossia. I'm skimming through the manual of every package I'm loading (texdoc packagename on the command line produces the manual). If I encounter an issue, I'm able to produce a minimal working example and get help.

If I were a template user, I'd have missed much of that. No idea how to discern flagship packages from unmaintained stuff. No way to produce a minimal working example and get help.

Starting with LaTeX with a complex template is like downhill racing on a mountain bike without having ever learned how to cycle on a bike: Hell.

Answer 2

To start with a quote (from Wikibook):

If a friend of yours wants to give you his/her template, it is a very nice gesture. Say Thanks, but no, Thanks. You won't believe how many strange stuff is in there without him/her even noticing it. All those are little tripwires that you don't want in your document. Unfortunately, the same is true for many templates you can find online.

The following text summarizes some common points. (In the following text the term "template" is meant for every piece of code you'll find out there providing a full-featured TeX document which just misses the content and, of course, those custom document classes you'll find everywhere.)

Deprecated commands

Many templates you'll find are built on the command set of LaTeX 2.09. That includes commands like \bf etc. which should not be used in recent documents. Those old commands may cause some harm especially working with some document classes (see, e.g., KOMA) you may want to use.

Bugs

Many templates have crashingly bad code, often from using packages and classes that are incompatible with one another. (classicthesis is a prime example.)
_{above sentence taken from a comment by Alan Munn}

In addition some problems with maintenance may occur as there are templates that were published once, but are not maintained anymore. If you encounter bugs (bugs are not not modification requests) in such a template, you may have to solve them on your own.

Single-purpose templates

Another problem with templates is that you will find many templates made on purpose. So a thesis template for university X probably meets the style requirements of university X, but not Y. You should not even try to use it at Y, because most templates do not want you to modify them.

Overload of packages

Many templates also tend to load a whole bunch of packages. Some of them aren't even needed and some of them may clash with packages you need to use. You could try to rewrite or delete parts of the template, but that's cumbersome.

Predefined structure and dependencies

Some templates (especially for bigger projects) also force you to use a specific file and folder layout, because they link to an image file or a file in another directory. Sometimes templates even include a reference to a package which is not distributed with all distributions, but only some (or has to be downloaded).

It's getting even worse if the name of the template clashes with other packages (or if it's too general like thesis.cls).

Problems in typography

As in every other subject you should understand what you're doing. Some templates change typographic conventions and want to force you to some specific style. That's especially problematic as typography differs around the world. American style is not always applicable in Germany, for example.

Mostly it's better if you learn how to present your data (which is also important) in the traditions of your country's typography (look, e.g., at booktabs etc.).

Suggestion

Do not use a (complex) template if you do not have to. If you're studying at a university forcing you to use a specific template, you should use it, but if you're free to choose your style, just start off with a very basic document and spend some time learning LaTeX to get the style you want without using a complex template which does not suit exactly your needs.

Answer 3

I'm a template user ...

I'm using them constantly: When I write a letter, I use an older one as template. At every project my first step is to look if I have or know about some older code that I could use as a starting template. Quite often the templates I use are not good – they are old, sometimes buggy, or they don't really fit. Many of my templates are rather complex. They nevertheless save me time: I don't have to retype everything, I don't have to wade through documentations to find out command names and syntax, I can reuse ideas.

So I don't find it very convincing to tell people not to use templates at all.

... but I have the knowledge to handle the templates

And this is imho the main point: Many users use templates to avoid having to learn LaTeX and read some documentation. This almost never works.

So if you want to use a (rather complex) template or a local custom class:

Imagine that you get a fatal error and nothing compiles, or that someone tells you to change the header or the bibliography style, or that you realize in the middle of your work that something in the template doesn't fit your needs. Consider if and how you can handle such a problem.

If the answer is one of these

• I know enough about LaTeX to debug or adapt the template.
• I have a friend with enough knowledge who will help me.
• I have access to some professional support that will help me.
• I understand enough of the template and of LaTeX to be able to build a minimal example and ask on tex.SX or some other help site.

Then go along and use the template if you like it. If you are relying on external support for problems perhaps ask them first if they recommend the template.

If the answer is

• in case of problems I will put everything in a zip file on the net and then hope to find some stranger who spends a few hours to disentangle everything for free.

Then you had better reconsider the use of the template. Even if you find help you seldom find it fast as there are far less people around who are willing to spend that much time on a problem and often you get the help only after a lot of begging and disagreeable discussions about why you use a template that you can't handle.

If the answer is

• I won't get problems – the template is perfect.

Good luck.

Answer 4

Disclaimer: This is the Advocatus Diaboli writing.

Personally, I also fully agree with the point of @TeXnician. There is so much value in building up a document from scratch. Fitting it to it exact needs. And learning new things in that process.

But, I think this misses a few things as it describes a very specific kind of LaTeX user. There are for sure people who want to use the system without learning very much about it - I think the whole spectrum is present. And this should be OK! Hence why LaTeX templates should not be avoided by users.

To be fair: the current state of template use is quite a disaster. There are so much undocumented, unmantained and fully overloaded templates containing bad hacks. And on the other hand there are users who pick them. And since I am firmly convinced that this question won't be able to stop template use here is a set of advice to users who are inclined to use templates: 1) Check if there is documentation for the template or at least some comments in the code. 2) Check if someone is taking care of keeping the template up to date and avoid using templates by John Doe, version 'I simply uploaded this to the internet, good luck...' 3) Check for unnedded packages. This might be hard to judge in the beginning and will most likely require a few minutes of reading. A (really rough) rule of thumb is: If there are more than 20 packages loaded by default beneath each other there might be stuff you won't need at all. 4) Check for bad hackery. Probabilly the most hard to assess. Maybe consult your local TeXnician for that :)

Apart from that it could be beneficial to declare guidelines for template authors and to have some kind of certificate for authorised LaTeX-template-writers. The guidelines are quite obvious, I think:

• The format: .sty or .cls (IMO this should be limited even to packages only) with an according .tex file setting it up.
• A Meaningful name to make it easy distinguishable for users (as for the comment of @samcarter)
• Healthy balance of generalisation and specific features
• Maintained version on CTAN
• Presence of a documentation

Ideally, new users would then be pointed to those templates in the LaTeX starter guide and briefed that other templates should not be used - but this is really more about TeX politics, which I honestly do not know much about...

Answer 5

I agree 100% with TeXnician answer (+1), so I'm just going to emphasize some aspects:

1. Templates are very attractive for novices since supposedly the template will do magically the most of the hard work for you: learn LaTeX "will be nearly irrelevant", but the premise is miserably false, even with the best template. You will face to your own ignorance before the cock crows twice.

2. The more miracles you wait, the more mistakes you'll find. Heavily tuned classes and endless preambles are created mostly for awesome visual effects but even working fine, in the hands of others than the author, could be used unexpectedly. The result is often only cryptic errors, novices' nightmares. Example:

   LaTeX Error: Float (s) lost.

   English translation: they float, Georgie, and when you’re down here with me, you’ll float, too.

3. Templates, custom classes, and macros often have not a decent documentation, not even a simple comment in the source code. Therefore, not only is a pain debugging error. Also, discover the template features and how to use them could be annoying.

4. In case of custom classes or packages that are not in your distribution, you should maintain these files in your working directory or your some other available path. Over time, in both cases there a risk of being outdated or lost (you save the document, but not the required files, for instance). This will not happen using your distribution standard classes.

5. We all have the obsession to do things in our own way. Even with articles to submit to scientific journals. Even when this obviously will not make happy to the editor (that provided a template just to avoid your author "creativity"). If we will end up customizing a tangled custom templates... why not start with a clearer one, as \documentclass{article} \begin{document} text here \end{document}?

Answer 6

The question is not about avoiding templates. It is about avoiding templates that you don't understand.

beamer is basically a template with ridiculously complex (and often annoying) code. But because it works and consistent, people use it and spend extra time and effort on it to learn it. Because it is learnable (well almost). memoir is also amazing and you customize it to the nuts and bolts (so is KOMA). But the catch is that these all have great manuals. A random template doesn't. So that is the atom of evil.

If you pick up a random template and don't understand any part of it then you can't modify it. Because you don't understand what it is doing you start searching online and things get out of hand.

But all this mess is because of google not sorting the search results chronologically. You can see an archaic plain TeX and last-year's-package trick in the same document. This is not user's fault. Because TeX is also archaic and a horrible language to learn without any proper version information or other indicator, you pick up a trick from a page where it still has these animations

Then you pick another piece of code from here asked last month. Somehow they don't work you wonder. Also TeX is super esoteric, so are its users. So you don't get a clean answer to very simple problems. Most of the arguments if lasted more than 5 minutes leads to Turing completeness.

Everything might or might not be a good code. So things get convoluted really fast. And you give up and say screw this, is there a readily made thing which I can use?. At that moment, you can make a very simple choice:

If you would handle the code or at least you know roughly which part is responsible for the header and other part is the title page, you can use it. Otherwise do it your own. Because the time you spend debugging the foreign template will be longer than your own design problems solved here when you ask properly.

Can't resist...

Answer 7

Templates provide examples. People learn from examples very fast, compared to other types of documentation. Besides speed, also a lot of detail is conveyed by seeing a command or environment in action. People teaching programming courses will agree with this, and LaTeX is no different.

A template usually provides a complete, working document, that shows many features of the class and packages involved, including ways to modify the default behavior. This can be very helpful for users, both beginners and experienced ones. It gives you a head start, and saves the trouble of collecting the large amount of scattered knowledge needed to use advanced features (i.e., the user doesn't have to reinvent the wheel).

Without templates, many users would not be able to create complex documents. With templates, they can. Fast. Personally, I was very happy with my PhD thesis template, which allowed me to write a nice document, and I also learned a lot about LaTeX in the process.

It's not surprising that many packages on CTAN include, besides the regular documentation, a template with the most important use cases. They are there because it is useful.

So far for the good news. The bad news is: many templates available online are poorly written, they have all kinds of problems and trying to tweak them to your own needs may take more time then writing a new document from scratch, even including the time needed to find out how to write things from scratch. See @TeXnician's answer (and others). But this is also part of the learning process. With some experience with different templates, users will learn to distinguish a good template from a bad one. Use what is useful, forget the rest. LaTeX is hard and frustrating, don't make it more difficult than it already is.

Answer 8

I once attempted to produce a resume, with classicthesis template, I even asked a question here in my attempt to get it to work and found myself going down one rabbit hole after another. It just got more and more frustrating, and complex, as I attempted to force the foreign template to do my bidding. It somehow took on a life of its own; the more I tried to make it do what I wanted, the more weird stuff happened as a result.

The template example looked really good, and so I thought, hey why not use the template?

Finally sanity set in, and I took the design elements from the template that I liked, and made my own template. Making my own took vastly less time.

So, my take on it is how do you want to spend your time? Trying to figure out somebody else's wabbit hole, versus creating your own. At least I somewhat understand my own perhaps quirky coding.

But, it was a very educational experience...