2

In my company we're using Latex to create our internal and external documents. The problem is, depending on personal preferences everyone is creating different document styles. Now my goal is to introduce a Latex template that covers all needed style configurations (e.g. fonts, headings, tables, graphics etc.) and unifies them.

  1. What's a good point to start? What should be covered in a company template and there good examples out there?
  2. How can I make sure it stays maintainable? I don't want to flood it with packages initially but I also wanna keep the users from randomly add other packages.
7

I have no experience writing company TeX templates, so maybe someone else who has dealt with them can chime in, but let me share some thoughts anyway.

There are quite some things to consider before you start writing your company template. You'll definitely want to read https://github.com/johannesbottcher/templateConfusion, What is a template?, Why should you avoid using (complex) templates? and linked questions.

The answer, as always, is: It depends on your situation.

What's a template anyway?

It is not entirely clear what a template actually is in the context of TeX documents.

It may just be an example document with a pre-filled preamble, that loads some packages and adjusts some settings, and an almost empty document body that your users would fill. But it may also be a document class (.cls) or package (.sty) that people load in their actual documents. A template can be a complicated arrangements of tens of files, or one file of roughly hundred lines of code. So whenever you hear two people talk about "TeX templates" you need to be aware of the possibility that they are not actually talking about the same thing.

Fixed vs variable output

If your company has a comprehensive "corporate design" policy and strict layout and design rules then it is quite clear that your template should enforce that design and you can hide behind the policy to explain why people can't change these things.

If on the other hand there are no rules, you can still decide to enforce a reasonable layout and tell people not to change it.

Lastly, you may decide that you want to give users control over the document layout. You can do that with only a few options (lets say a user can choose between a serif and sans serif font or adjust the font size via simple options) or you can allow for more customisation. The more customisation and variation you want to allow, the more complicated and harder to maintain your template becomes.

User expectation

You also need to take into account the expectations, needs and requirements of your users.

If you have many TeX users who expect to be able to keep using the code they have been using for years and their favourite packages, you either need to make your template compatible with their code or have a good explanation why they can't use their code with your template yet should still use your template. Of course making a template compatible with almost everything people might throw at it while at the same time implementing something useful is extremely hard.

Do your users expect to just write their document without any further ado, or do they want to be able to control every bit of it?

Scope

Templates for plain and simple text documents are easier to write than templates for complex documents with mathematical formulae, chemistry, tables, graphs, bibliographies, ... As soon as functionalities that are normally realised via packages come into play you have to choose between (1) explicitly loading packages in your template thereby blocking the use of incompatible packages with a similar scope and loading stuff that some user may never need or (2) not loading anything and letting your user decide, in that case a user may run into incompatibilities and you may not get the uniformity of company documents you strive for.

Documentation

Documentation is a crucial part of writing and releasing a template. Ideally you do not only document the commands and options of your template, but also explain your design decisions and give hints for further use of the template. If your template loads relatively few packages, the documentation could list useful packages that people may want to load to get the feature XYZ.

If possible also offer help/support for your users: Not only when the template does not work as expected, but also for stuff like "how can I ...?". If your users turn to you when they need anything, you know if the template can be improved and you can make sure that they don't copy a random assortment of code off the internet and then complain that it doesn't work with your template.

Maintenance

Usually TeX code is easier to maintain if it is short. So ideally you would only implement what is absolutely necessary. Find packages that do the work for you, but make sure that all packages you want to use work together properly. Do background checks on the packages you want to use and load only as many packages as really needed. Try to use only high-level features that are unlikely to change if a package is updated. (Package authors usually value stability, and so they keep the user/high-level interface as stable as possible, but lower-level code may change.) If you have to use undocumented internals make sure you regularly check back that your template still does what it should do.

Usually I would recommend to keep the template up to date with development in the TeX world. Update your template if new features of packages you use mean you can find a more elegant way to do stuff. But in a corporate environment where you normally don't have full control over your (TeX) system, updates can be hard to come by... Actually, this ties in with another factor: Backwards compatibility. Especially for company documents you want to make sure that they still compile properly after a while, so after an update to your template the user interface should not be changed in a way that would break older documents.


If you are looking for examples, there are quite a few things on CTAN (see for example https://ctan.org/topic/dissertation - thesis templates are by far the most common TeX template).

classicthesis and cleanthesis are more generic templates that don't follow fixed guidelines and so at least leave users thinking that they should be able to change the appearance of the documents as they please.

Then there are classes like msu-thesis that implement the requirements of a university and usually don't allow for arbitrary layout changes.

  • That's a helpful answer. I'd say most of our documents can be completed using simple text, mathematical formulas, tables and graphics. It's not my goal to set to hard boundaries but I want to assure that two different user manuals still have the same overall design in regards of font, font-size, table styles etc. so your input of writing a documentation for the template, what in my case is a example-document, may be very helpful for the users. – Humpawumpa Jun 19 '18 at 15:52
  • Very good summary. – Johannes_B Jun 20 '18 at 4:50

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.