Published: Sep 26, 2024 by Richard Sezov
To reiterate: to gain all the benefits of switching to a Git-based editorial process, my team would have to switch to a plain text format. We were now going right back to where Professor Provine had pointed me.
I briefly considered his prior decade recommendation of LaTeX, but rejected it. It is primarily designed for creating PDF books, not searchable websites containing HTML-based documentation. I narrowed the formats down to a short list: Markdown or ASCIIDoc.
ASCIIDoc had more features, but Markdown had more industry support. In particular, I needed a Java-based parser (a program that converts from the plain text format to HTML) that would be able to run inside of Liferay. I found this in Pegdown (now discontinued), which seemed to be widely used and well supported. Markdown became our standard.
We took Liferay’s Knowledge Base application and enhanced it so it would support Markdown and its images, zipped up in an archive. We would write the documentation in Markdown, run an Ant script to build the .zip file, and upload that to our Liferay Knowledge Base. I defined the file system-based format for how the documentation would be organized and ordered, and our importer automatically created the navigation.
The Liferay Developer Network was born.
Our writing process changed considerably. Now each technical writer had to choose a text editor, not a word processor, as his or her tool of choice. The first text editor I chose was JEdit. It is written in Java, my language of choice, and I thought maybe if I needed to, I would be able to write plugins for it. It supports Markdown (as does pretty much everything else), has tons of features, and lots of theme options. It has Git support, can show the differences between versions of files, and has an easy-to-understand interface. I jumped right in and started using it.
I’d stumbled into what has now become a recognized methodology for documentation, called “docs as code.” Since I’d been a developer and was familiar with version control systems, treating documentation like code had been natural for me. Of course, now it’s well recognized that this is the best way to manage technical documentation, but at the time, we were doing something new. Git itself was new, and GitHub had only existed for two years.
Our new process was far better. Writers could write individual articles, send each other pull requests to collaborate, and then send them to me, and I would do the final editing before pushing the changes up to the repository. At the end of the week, I would build the docs and deploy them to the site. The tools developers use to collaborate on code are the most robust for showing who wrote what, what was written, when it was written, and exactly what changed. The amount and scope of our documentation grew rapidly.
My daily job turned out to be the catalyst that moved me into writing in a plain text-based format, every day.
Part 1 of this series is here.
Part 2 of this series is here.
Part 3 of this series is here.
Part 4 of this series is here.
Part 5 of this series is here.
Part 6 of this series is here.