The Making of adoc Studio

In mid-2004, we realized that documentation is important for our project management software Merlin Project. While the developers worked diligently on the code, the service team took care of the documentation. Thus began a journey that only ended successfully many years later. I'm not talking about the content of the documentation, because a manual for continuously developing software is never complete anyway. Our biggest problem was always the software or technology we used to write the texts and create the final files.

Microsoft Word

Of course, in good business fashion, MS Word was automatically used. It should be noted that the 2004 version was a very shaky affair under Mac OS X (the name of macOS at the time). It was with great pain that we got documentation for Merlin 1.0 up and running. As the Word.doc binary files did not fit into a VCS (Version Control System) - we were still using Subversion at the time - hundreds of different copies of the manual were spread across various file servers. Of course, each document had a different status, but some of them were only slightly different.

We very quickly lost the overview and thus some good versions of the Merlin manual due to ill-considered deletions. We realized that we couldn't build a software business on this.

LaTeX

For Merlin 2, which was to be released in 2006, a radical change was suggested to us by our business partner Tom Alby:

If you need extensive documentation, use LaTeX. You just take care of the text, the system does the rest for you. That's it.

Of course, we had no idea about the language and didn't know how we were ever going to understand the almost unmanageable range of commands. But we immediately had the advantage that the texts were maintained in the new VCS called Git. So we gratefully asked Tom to write the manual for Merlin 2.

The result was excellent. In addition to the source texts, we also received an excellent-looking PDF.

Our naïve plan was to maintain and update the manual ourselves. But in this case, we had not done the math, as they say. We were able to add new texts, but new sections became more difficult. And completely new sections or redesigns were simply not possible for most of the team.

Gradually, the team refused to put their hands on the LaTeX files. This meant that the second approach had also failed.

HTML

It must have been around 2008 or 2009 when we finally arrived at a slightly less technical approach. Since the ProjectWizards website was built by hand in BBEdit as HTML pages at the time, it was an obvious choice to create the manual in the same way. We had already learned from LaTeX to separate the content from the design. It worked the same way in HTML. "A global stylesheet formatted the HTML text files. Of course, everything also fitted back into the Git - we were happy.

The problem was PDF. At first we tried - relatively callously - to declare HTML the standard. We wanted to cover up the fact that we couldn't produce any good PDF files at the time (apart from poor PDF printing from the browser). But customers quickly showed us this; the demand for a manual as a PDF file quickly grew louder and louder.

So the text was copied from the browser and pasted into MS Word to create a ... I'll spare us the further sordid details at this point.

In this way, we somehow muddled our way through the Merlin 2 period. But it was a far cry from a well-structured development of the manual texts - and their output.

Markdown

With the development of the third version of the now renamed "Merlin Project" software, everything was supposed to get better! We had learned from our mistakes in the first few years and set ourselves a goal: A good-looking manual in PDF and HTML. So we drew up a list of requirements that a documentation technology had to fulfill:

• The texts must be written in ASCII using any text editor.

• The encoding must be UTF-8.

• The standard output must be HTML, but PDF and ePub must also be possible.

• We must be able to influence the design of the output.

At first glance, Markdown, which was already quite popular in 2011, met all the requirements. There were even the first apps that explicitly relied on Markdown, such as Ulysses from our friends in Leipzig.

Unfortunately, we kept realizing while writing that the language was very limited and we weren't getting anywhere. It was lacking in every nook and cranny:

• no tables

• no special content blocks

• the formatting of the images was only very rudimentary

• and many other problems ...

So we needed a better approach for Merlin Project. Our advantage was that the new version of the project management software was not yet ready. But that's another story.

AsciiDoc

The idea for a new approach came up in a team meeting: AsciiDoc. A language that was invented and developed by a certain Stuart Rackham back in 2002. The basic dialect is very similar to Markdown, but much more advanced in many areas and significantly more flexible.

Initial tests were positive. We were able to convert our existing texts into AsciiDoc notation relatively quickly and were very pleased with the results. Only the speed was not optimal - especially for longer and complexly structured texts. But what did we care about the time it took to build the texts? We were happy with the results. Many documents were created. From smaller instructions that were only intended for internal use to public documentation. At some point, we had also transferred the Merlin 2 manual to AsciiDoc and were able to present customers with a real PDF again.

Then the rumors started that Stuart Rackham would no longer be able to maintain his AsciiDoc. Naturally, we were very worried; because by now - it was around 2013 - 100% of our public documents were based on this markup dialect. Eventually we learned that a Dan Allen would be taking care of AsciiDoc. We were relieved.

Even before the release of Merlin Project in 2015, we were able to test the new Asciidoctor with the old AsciiDoc files. The results were identical, only the speed of building the documents had multiplied. Our new wizard was then released on the same day with the new manuals in HTML, PDF and ePub.

The consequence

AsciiDoc and later Asciidoctor has been in use at ProjectWizards since 2012 and is considered a set tool. We have appealing styles and themes for all output files. And maintaining the existing documents was and is a pure pleasure. Only the editor was good with BBEdit, but not yet perfect.

Another challenge arose more and more from 2012 onwards; the iPad. After we already had a Merlin Project version for the Apple tablet, we wanted to be able to write or at least correct our texts on the go. That worked, of course, but there was no preview of our Asciidoctor texts.

So we took a close look at all the editors that worked on both platforms: macOS and iOS. Unfortunately, our in-house editor BBEdit is only available for Mac. We had a chance with Ulysses, which also runs on the iPad. But Markdown was set as the language there.

But we weren't just looking for the iPad. There were also one or two challenges for the Mac. Everyone in the team chose their own editor. That was fine in principle, of course. But only up to the point where some editors did not set the file encodings correctly. The result was broken special characters or missing umlauts. These problems spoiled the use of Asciidoctor to some extent.

Also the color highlighting of the Asciidoctor syntax in BBEdit was not satisfying, so I wrote a - rather bad than good - BBEdit CLM (Codeless Language Module). The preview was basically the same file in the browser with the Asciidoctor.js Live Preview. This was not practical in every case. And it didn't work at all on the iPad.

Technical Writing on Mac, iPad & iPhone

Start Free Trial

The Search

So the search for a common editor was intensified. We asked friends and other developers for an editor and the answers were mostly the same: Over the last few years, a number of so-called IDEs (Integrated Development Environments) have appeared on the Mac. These were given special extensions to support our desired language by the open source community and the Asciidoctor community in particular. We were all able to work with them, the only problem was that they didn't run on the iPad. It was also clear in many places that these IDEs were built for software developers for the various programming languages. There was no thought of writing long texts.

Until we remembered the start of Merlin. The initial spark in 2003 was the lack of project management software on the Mac. Today, we lack an AsciiDoc environment on the Mac and iPad.

However, this was not easy to solve, as interpreted languages are not allowed to run on the iPad. This meant that Asciidoctor was excluded from the range of possibilities right from the start. On the other hand, this was also an advantage, because as ProjectWizards we are only interested in software projects that cannot be reprogrammed immediately. So there has to be a certain level of innovation so that many competitors do not immediately appear on the market.

So it was clear to us that our product needed its own parser. And not only that. All of a sudden, the wishes for a non-existent project came flooding in.

The Pre-Project

In October 2020, a text system for Mac and iPad based on AsciiDoc was on the list of topics at a team meeting for the first time. And from then on, things went from strength to strength. In January 2021, an initial goal was defined and the first mockups had already been drawn. It was clear to us that Merlin Doc - as the product was called in the first few months - should be a very easy-to-use IDE for AsciiDoc texts on macOS and iPadOS.

This also made it clear that compatibility with existing AsciiDoc projects had to be very high. Our first model was Pages or TextEdit. No WYSIWYG (What you see is what you get), but also no configuration hell. Just something pleasant in between.

And so the starting signal for the new project was given in 2022. This began under the second project name; FinalSpec.

The first six months were characterized by experiments. In so-called prototypes, techniques were tested, rejected and also found to be good.

Things got serious in mid-2021: the kick-off for an MVP (Minimal Viable Product) marked the end of the play and test phase.

The goal of traveling the country with an MVP from the end of 2022 was narrowly missed. From June 2023, I was able to show our new tool to major customers, associations and colleagues and gather initial feedback.

The feedback was outstanding! adoc Studio - as the product was now called - was enthusiastically received. Everyone actually wanted to get started with it straight away.

We - and a few other brave testers - have been using adoc Studio since July 2023. The initial version 1.0 is still pending. We are currently steeling the product through a very extensive beta test. You too can help us to make adoc Studio the perfect integrated writing environment for technical authors.

Concluding Thoughts

We are proud of adoc Studio and believe it can revolutionize the process of creating and editing documentation. We hope you will love it as much as we do.

We are excited about the possibilities adoc Studio offers today and look forward to the future. We have many ideas for adoc Studio. But our journey is just beginning and we invite you to join us. We look forward to many more years of learning and growing together with adoc Studio and the AsciiDoc community. Please do not hesitate to contact us with any questions, suggestions or requests.

Welcome to the world of adoc Studio, we look forward to seeing you!

— Frank Blome