102 #documentathon
These are my notes from the Software Documentation with AsciiDoc session at the Workshop-Days of the Swiss Open Systems User Group (CH Open) on September 2, 2024. You can also find the draft of this post in AsciiDoc format here.
NEXT: 🔜 find me at DINAcon on November 21, where I've posted a Docathon challenge for us. Please drop me a line over at Fosstodon or by email (oleg @ this domain) if you have any questions.
The workshop was run by Christian Heitzmann, a highly experienced software developer who runs SimplexaCode AG in Lucerne. As a technical writer, he regularly documents the software architectures for companies, teaches university courses in Machine Learning, and regularly writes articles for IT journals.
Documenting Python Code is a recent presentation Christian gave at PyCon Italia 2024, that also serves as an excellent introduction to documentation awareness as a critical facet of the software developer’s work. I heard Christian's pitch at Open Education Days last year, where you can also find a downloadable set of slides in German.
Our workshop description, translated with help from DeepL:
With a simplified markup language - in this case AsciiDoc - the documents can be created and edited in any text editor. All content and configurations remain easily readable and editable, without the need for idiosyncratic WYSIWYG programs or wiki platforms.
Software developers appreciate the proximity between program code and documentation as well as the option of placing the raw documents directly under version management. Readers of all target groups appreciate the professional, uniform and well-maintained appearance of a documentation structure generated in this way.
This workshop will certainly help to clarify software documentation, provide new ideas and open previously unknown doors. You will learn why previous attempts to document your own software architecture only worked in the short term at best. Using many practical examples, you will gain an overview of the impressive possibilities that arise with a doc-as-code and diagram-as-code approach.
The focus is on getting to know and practicing AsciiDoc as a simplified markup language. All this is accompanied by instructive explanations of the organizational who, how and what of software documentation.
The aim of the workshop is to quickly and effectively introduce participants to the use of AsciiDoc for software documentation and beyond. They will learn how to use this simplified markup language to create clear, professional and consistent technical documentation as well as non-software content. In short, after this course, participants will be able to use AsciiDoc to simplify and improve their documentation processes - regardless of the area of application.
— Christian Heitzmann
(You can find the full session description on the Pretalx page)
We started the session with brief introduction of the participants - the consensus in the room was quite clear: technical writing is a big deal for all of us! Whether we manage to enjoy the process, or not, get paid for it, or do it as a volunteer, it is the essential "glue" of technology. From code comments to user manuals, API documentation to Q&A forums, documentation takes up a lot of time, and it is a great skill to develop.
So what, exactly, is AsciiDoc? Wikipedia defines it as one of several "lightweight" markup languages:
A lightweight markup language (LML), also termed a simple or humane markup language, is a markup language with simple, unobtrusive syntax. It is designed to be easy to write using any generic text editor and easy to read in its raw form. Lightweight markup languages are used in applications where it may be necessary to read the raw document as well as the final rendered output.
For instance, a person downloading a software library might prefer to read the documentation in a text editor rather than a web browser. Another application for such languages is to provide for data entry in web-based publishing …
If you have worked at all with open source communities, you will have heard of and probably used Markdown. AsciiDoc is less prominent, but embedded into a great number of open source projects and development platforms, exemplified by the support for it on GitLab, as an optional Gitea setting, and for viewing 'non-code files' on GitHub.
Stuart Rackham wrote the original Python-based tools for AsciiDoc in 2002 (i.e. the libraries ‘asciidoc’ and ‘a2x’). Most of the Git project documentation was written in AsciiDoc. Today, the more widely used one seems to be the Ruby-based AsciiDoctor. There interesting history of the project is here.
The best thing about AsciiDoc is how easy it is to get started - with the right cheatsheet (or Spickzettel, auf Deutsch), like powerman.name or the one above, you’re off in a jiffy. There are many more learning resources and tools for Markdown, such as GitHub’s excellent tutorials, which in theory could be easily adapted for the basic syntax of AsciiDoc. However, the target market as a whole seems subtly different - closer to templating languages, such as Liquid.
Peter Conrad
There is a prominent body of blog posts and presentations that try to convince you (Eric Holscher) to switch (@bandantonio). To me, the most basic reason is the same as knowing another spoken language: to explore another document culture, and just for more variety. Take a look at this post for a quite illustrative history of markup languages (Hackernoon). The momentum for Markdown also means it needs to be even more critically considered and aesthetically questioned. We are not about to write Markdown off, no pun intended, as it is effectively the lingua franca of open tech, the ninja warrior of modern tech writing.
"The value of Markdown is that it allow us to enter with very low friction into worlds that maybe haven’t even thought about docs.” — passo.uno
The recently released update of the CommonMark spec interestingly compares Markdown to AsciiDoc. I’d also like to point out the interesting road up ahead for AsciiDoc standardization. Converters are very helpful, and Pandoc was mentioned as the best tool for going to-and-fro these days. You can use Kramdown AsciiDoc to automate the migration from Markdown to AsciiDoc.
When I typed pacman -S asciidoc on my Arch Linux system, I got a different package - the Python library (asciidoc-py), rather than the converter. When I typed "asciidoc online editor" into a search engine, I got a rather out of date project. These issues need to be addressed, though it works fine for learning the basic syntax and doing some tests. I couldn’t find any other supported web IDEs, as suggested here (CodiMD issues).
There are a few fascinating, but sadly rather abandoned AsciiDoc projects out there, like this OpenOffice converter, a TiddlyWiki plugin, even a full-featured WYSIWYG desktop editor called AsciiDocFX. Today, the most important is probably publication of websites and online documentation. I have already used Pelican for publishing my static sites with Markdown, and AsciiDoc is well-supported by it through the asciidoc3_reader plugin. Note that Sphinx support is a bit patchy via asphinx.
You’ll almost certainly find a good plugin for syntax highlighting and more in your preferred IDE, such as Sublime Text. And maybe you will find a good hack, like this tool for bloggers. Delight your inner Sherlock Holmes with yonkeltron/ztl.
For the hands-on part of the workshop, we mostly used VS Codium with the AsciiDoctor extension. We went through table design, checked out the very sophisticated and dense set of options. The best part for me was being able to load in remote data formats.
Another quite fun part of the workshop was embedding diagrams, using the cloud-based Kroki, or directly with Asciidoctor-diagram - which I had working quite well with Mermaid after I installed mmdc (mermaid-cli). I had never heard of PlantText before, but it is a quite interesting tool for UML diagrams and flowcharts.
Getting into the more advanced AsciiDoc practices of including files and procedures, we talked a bit about the history of encapsulation. This reminded me of a nice documentation hack in the Web development world: the Pattern library.
Christian recommended the C4 method to us. See the Arc42 template for architecture communication and documentation, and the book of software architecture longevity. I'd also stress the value of having a Style Guide in this context, with tips for future documentation writers (even if is a future self) - for example, see Apache Kudu, Spectrum OS, VSHN and Google.
A fellow participant reminded us of the long path travelled. In the end, for professionals and software teams, it’s a question of building documentation infrastructure. The Django project has quite a few lessons on this for me.
Christian suggested for further software engineering interest to dig into the Antora tool. We didn’t cover this, but I started looking into automated testing to calculate documentation coverage. Or go much into language-specific practices like document strings in Python, or in Julia. The quiet "Elephant in the room", was using LLMs to co-author your documentation:
"my hunch is that we’re about to see a fascinating new twist on the old idea of literate programming. Some explanations can, will, and should be written by code authors alone, or by those authors in partnership with LLMs. Others can, will, and should be conjured dynamically by code readers who ask LLMs for explanations on the fly."
"The best kind of comments are the ones you don’t need."
"Do not believe any programmer, manager, or salesperson who claims that code can be self-documenting or automatically documented. It ain’t so."
Final thoughts
The workshop with Christian has been an excellent refresh on the fundamental disciplines of software engineering, and introduced me to new concepts and powerful documentation techniques.
Going through this session has given fresh perspective on developer relations — helping more people discover the value of technical writing, and engaging in this collaboratively is something I will continue to promote online and offline (from hackathons! .. to documentathons!)
<3 Many thanks to CH Open and to Christian for the workshop <3
Find the workshop materials and more in the SimplexaCode archive:
As a last bit of inspiration, I would like to share a video on 'beautiful' documentation from the OpenBSD community:
How good is OpenBSD Documentation, actually? - Douglas Rumbaugh
