On the Joys of Templates

How it Started

For a project I was asked to replace a procedural document generator with one based on templates. The rationale was that templates are simpler, more flexible and the end users can edit them to their liking instead of requiring the help of developers to do that. And yes, templates are completely en vogue these days.

I had a bad feeling about migrating to templates right from the start. Unfortunately I did not have the arguments at hand to question the decision. Now, after the whole experience, I do, and I wanted to share them here.

The sweet spot for templates is static documents, like forms. The computer will fill in the blanks and there you have your document. Great. The problem is what happens next. You send your generated document to the stakeholder, who gets back to you saying: "Good job! My team gathered some feedback, and we want to make some parts of the template optional depending on... several things. Should be easy to add that, right?".

What Happened Next

Over time, templates tend to get more complex and dynamic, not less. No worries through, templating engines are crazy powerful these days. They allow going down the path away from static documents a long, long way. Soon, our Microsoft Word templates contained for loops, if-else constructs crammed in table cells and all of that mixed with regular document content and styling. Mixing code with styling. Code in a document. Wait a minute, do I still have syntax checking now? Nope. Or line numbers to locate a problem in a template? In your dreams.

At some point, we reached the limits of what our templating language could reasonably do. At this point, we entered another stage. Things went from painful to obnoxious. What happened now is that document content, which could no longer be generated in the template itself, was moved into application code. The application generated the document content procedurally while the document only contained a placeholder for the generated content. Now, just consider where we have ended up. Application code has moved into the document while document content has moved into application code.

While code and content are now in places where they should not be, responsibilities of developers and stakeholders got mixed up. We started out by delegating maintenance of the templates (Word documents) to the stakeholders. This is in itself a good idea. The stakeholders are comfortable editing Word documents, not code. The developers are comfortable editing code, Word documents scare them.

How it Ended

In the end, the developers found their code moved from their favourite code editors into Word documents. Microsoft Word is an environment they rather avoid for code authoring because it offers no syntax checking or debugging options. At the same time the stakeholders backed off from touching the templates, afraid to break the code contained in it. So now the developers had become responsible for maintaining code contained in Word documents as well as maintaining the document content and layout mixed into their code. In my opinion, that is not a great situation to be in.

One small anecdote to top it off. At one time I was faced with a bug in the template. The renderer said the template contained a variable for which I did not specify a value. I was pretty sure I did. It took me hours to figure out what was going on. In the end, I figured it out. In the Word document, the variable was part of a section title. The title was styled such that it was displayed in capitals, even while the text itself was part lower case and part upper case. Any differences between upper case and lower case characters becomes invisible. As it turned out, the variable had a lower case character that should have been upper case. Go figure...

I do understand why templates are attractive. However, great care should be taken when applying them to anything but form-like documents. For non-trivial documents, or documents that could advance over time, think twice.