DEV Community

Bambang Purnomosidi D. P. for Zimera Corporation

Posted on • Edited on

AsciiDoc(tor) for Technical Documentation

Writing is never an easy task, everybody knows. It is even harder for technical documentation since some pictures, diagrams, and technical drawings are meant to be in the documentation - with some explanatons of course. In software world, those things are also the main problems.

Some people think, and this is the majority, just use Word Processor software - be it in the desktop or in the cloud. This might work, of course, but might lead to inconsistency. So, we at Zimera Systems has the policy to use open and free tools to power our technical documentation. For this purpose, we find it easier to use Markdown + Pandoc but lately we move to AsciiDoc format and uses Asciidoctor and Asciidoctor-pdf. They are very easy to customize and creating PDF file is a piece of cake with complete theming guide.

The documentation title can be as simple as logo and the author, but can also takes full image so that we can use the whole picture when we really need to. Here's the simple title without the whole picture:

Alt Text

Table of contents will be organized automatically:

Alt Text

We love the picture and the admonium:

Alt Text

For us who are really passionate in coding, we especially love the callout:

Alt Text

We make our template open and you may get them at our repository.

Enjoy writing!

Image of Timescale

🚀 pgai Vectorizer: SQLAlchemy and LiteLLM Make Vector Search Simple

We built pgai Vectorizer to simplify embedding management for AI applications—without needing a separate database or complex infrastructure. Since launch, developers have created over 3,000 vectorizers on Timescale Cloud, with many more self-hosted.

Read full post →

Top comments (0)

Billboard image

The Next Generation Developer Platform

Coherence is the first Platform-as-a-Service you can control. Unlike "black-box" platforms that are opinionated about the infra you can deploy, Coherence is powered by CNC, the open-source IaC framework, which offers limitless customization.

Learn more