Documenting and tooling
Improving the OPENRNDR guide
A brief insight in how the OPENRNDR guide is improved with verified-to-run and visual examples.
The OPENRNDR guide is the go-to documentation for our Kotlin-based creative coding framework that mostly provides a high-level documentation of working with its API. Recently we have spent a considerable amount of time to improve the quality of the documentation found in the guide.
We found that the guide suffered from two key problems: incomplete and incorrect examples, and the lack of visual media to demonstrate what the example does.
The root cause for those problems lies in the lengthy process of getting example code in the guide. To add an example to the guide one has to create a new OPENRNDR program, create image or video captures of its output and finally place the content in a markdown formatted document. Those are quite a few steps to take –and for most of these steps there are no written guidelines to follow. This has led to some of the examples being written directly in the markdown. Without the use of any tools to verify those examples we ended up with a guide that is not as helpful as we want it to be.
Some weeks ago, after we improved the OPENRNDR API by adding a DSL to support very concise programs, the idea of having ‘runnable documentation’ popped up (–again–). This time, the OPENRNDR library had most of the tools needed to create short example programs, which can produce images and videos to demonstrate their output. To bring it together into runnable documentation all we needed was a way to compile written text and example programs together in a single file, extract and run example programs, and finally insert excerpts of the example program into markdown formatted text files.
In our search for tools that could do such a thing (we couldn’t find any) we found the kastree library with which Kotlin sourcecode can be parsed and turned into an abstract syntax tree (AST). With the AST in hand we are able to process Kotlin source files that contain annotated strings and expressions to produce markdown formatted text.
For example our “What is OPENRNDR?” looks like this:
We created a Gradle plugin called Dokgen with which a source tree of Kotlin source files can be processed and compiled into markdown documentation. Besides using the sources Dokgen uses per package property files to generate the guide index. Dokgen is also in charge of running the example code such that image and video captures of the examples can be inserted in the guide.
For those interested: the Dokgen tool and the sources to the improved guide. A word of caution though: the tooling is very much tailored to our specific needs.
Using our new tools we have been able to convert the contents of the existing guide and improve the guide with verified-to-work examples. The added ease of automatically generated image and video captures of examples should make the guide a whole lot nicer to read and browse through.
You can read or browse through the new and improved OPENRNDR guide at: guide.openrndr.org
