The manual was complete. Something was still missing.

I have been writing the speedata Publisher manual for almost 17 years now, pretty much since the first lines of code in 2009. And from the beginning, completeness was the goal: every command documented, every attribute explained, every concept covered somewhere. Over the years the manual grew into hundreds of pages, in German and English, and whenever a user asked something that was not in there, that was a bug to me — the answer went in.

And yet, for all those years, a nagging feeling never quite went away. The manual told you everything about the Publisher. But it did not really tell you how to write a layout.

Knowing all the commands is not the same as knowing what to do

The typical situation looks like this: someone wants to build a product catalog. They know their data, they have a design in mind, and they have a manual in front of them that explains <Table>, <Group>, <PlaceObject> and two hundred other commands in detail. What the manual did not answer was the question they actually had: which of these do I reach for?

Should the article list be a table or a set of groups? Should the data be transformed before the Publisher sees it, or handled in the layout? How do I get a “continued on next page” note under a table? These are the questions that come up in every real project — and the answers were scattered across concept chapters, example snippets and, honestly, my head.

I knew something was structurally wrong, but I could not name it. So I did some reading on how others think about documentation, and that is how I found Diátaxis.

Four kinds of documentation

Diátaxis, formulated by Daniele Procida, is a simple but sharp observation: “documentation” is not one thing. It is four things, serving four different needs:

• Tutorials: learning-oriented. Take a beginner by the hand and get them to a first success.
• How-to guides: task-oriented. Someone has a concrete goal and wants the way there.
• Reference: information-oriented. Precise, complete, made for looking things up.
• Explanation: understanding-oriented. Background, concepts, the why.

The four quadrants of Diátaxis: a tutorial teaches by doing, a how-to guide gets a concrete task done, reference is for precise lookup, and explanation provides the background. The columns distinguish the reader's situation: acquiring skills versus applying them at work, the rows distinguish practical steps from theoretical knowledge. After Daniele Procida, diataxis.fr.

The point of the model is not the taxonomy itself, but the insight that mixing these forms weakens all of them. A reference that tries to teach becomes chatty; a tutorial that tries to be complete becomes unusable.

When I mapped the existing manual onto this grid, the diagnosis was suddenly obvious. Tutorial? There, “Hello, world!” does that job. Explanation? Plenty: the topic chapters on the grid, page types, tables, fonts are mostly explanation, and decent ones. Reference? Existed, but scattered: the command reference here, XPath functions there, command line and configuration buried in the setup chapter.

And how-to guides? Essentially empty. That quadrant was the nagging feeling. “How do I write a layout ruleset” is a task-oriented question, and the manual had no task-oriented part.

The new structure

So I restructured the whole manual along these lines. The result is live now, in German and English.

The reference material is consolidated in one place: the command reference, XPath and layout functions, the command line, configuration, the glossary and the appendix. New is a thematic command overview, so you can find a command by what it does, not only by its name.

The manual chapters remain what they were good at – explanation and concepts – but with less duplication. Quite a bit of content existed twice in slightly different words; that is gone now, along with a pile of broken links that the reshuffling surfaced.

The real news is the new how-to section: recipes that each solve one concrete task from practice, with a runnable layout and data to reproduce it.

The recipes

There are seven recipes to start with: a table with automatic page breaking, controlling column widths, continuation heads and notes, breaking complex tables manually, the basic scaffold of a data sheet, a table of contents, and a keyword index. Two decision guides sit in front of them: should data be prepared up front or processed in the layout, and is a content block a table, a set of groups, or text flow?

That is a start, not a finish line. Which recipes come next should not be up to me alone — I am hoping for input from you: if there is a task you keep solving from scratch in your layouts, tell me, it is probably a good candidate.

Was it worth it?

Ask me in a year. I hope that I can come up with more recipes in the future or extend existing ones. Every time I create a new layout for a customer, I will think how to turn this into a structured explanation.

---

The restructured manual is online at doc.speedata.de, the how-to guides at doc.speedata.de/publisher/en/howto. The Diátaxis model is documented at diataxis.fr.