Disclosure: I am the author of AsciiLore, a commercial desktop app I built for the problem described below. I try to be clear about what it does and where it falls short.
The problem
Antora is a solid tool. It builds a documentation site out of components, and each component has its own versions, navigation and configuration. Pages are written in AsciiDoc, and much of the structure is defined by folder names and YAML files. For a technical writer, the writing itself is the easy part. The friction sits around it: a folder layout that must match what the build expects, YAML where one wrong indent breaks everything, and a build that has to be started from a terminal.
Consider a writer who needs to start a new version of a component. Depending on how the project is set up, that means creating a folder with the right name, copying files, editing a YAML file so the version matches, and checking that the build still runs. For a developer, each step is trivial. For a writer, each one is a place where things can go wrong without an obvious sign.
When something fails, the error message is written for a developer. It points to a file and a line number, but rarely says what to do next. A writer who knows AsciiDoc well can end up stuck on a problem that has nothing to do with the content.
For years I worked with this setup, and I saw the same pattern in my team: the people who wrote the content were not the people who could fix the build.
What we tried
Scripts. We wrapped the build in scripts so writers could run a single command. Scripts work until the folder layout changes, a tool gets updated, or a new component is added. Then someone has to repair them, and that someone is usually the person who wrote them.
Training. We ran short sessions on the terminal, YAML and the project layout. People learned the basics, but the knowledge faded quickly for anyone who did not use these tools every day.
Developers as the bottleneck. The fallback was to ask a developer. That works for one problem at a time, but it makes the documentation work depend on one or two people who understand the setup, and every small change waits for them.
None of this addressed the real gap. Writers needed to see the structure of the project and the effect of their changes, without keeping the file system and the build in their heads.
Whatever tool you use, a few habits help. Write the folder layout down in one place. Choose one version naming scheme and keep it. Make the build a single, documented step that every writer can follow. Ideally, writers shouldn't have to type anything into a terminal anymore, just run a batch file.
What helped
AsciiLore, the app I built, addresses parts of this in three ways. It shows a live preview rendered with Asciidoctor while you type. Saving, creating, renaming, moving or deleting a page starts a full Antora build, so nobody has to remember that step. And each project chooses whether its versions are folders, Git branches or Git tags.
I also kept editing where writers already work. Page text is edited in the external editor you configure; AsciiLore does not replace it. Antora and Asciidoctor remain the build tools, and AsciiLore has no rendering engine of its own.
What did not solve it, and what is still open
A tool can hide some of the complexity, but not all of it. Writers still need to understand what a component and a version are. AsciiLore makes that structure easier to see; it does not replace learning it.
A few open points:
- Platforms. AsciiLore runs on Windows, and on Linux as an AppImage. macOS is not supported yet, so teams with Macs cannot use it.
- Closed source. The code is not public. You have to decide based on the description and on trying the app yourself.
- Scale. I do not yet have data on how it behaves with very large documentation sets.
- Scope. Because page text stays in your own editor, AsciiLore covers part of the writing workflow, not all of it.
Availability
AsciiLore is a paid, closed-source desktop app for Windows and Linux (the Linux version is an AppImage). macOS is not available yet. A 14-day trial is available, and it does not require an account.
More information: https://asciilore.com/
Top comments (0)