Documentation, documentation, documentation

Writing software is more than writing code – good documentation is one essential aspect. A lot of the tools and libraries that make writing documentation easier use markdown as a file format, combined with metadata in yaml format and optionally some additional functionality, e.g. mdx – which combines markdown with jsx for JSX-based projects such as React.

If you think this sounds like the open-source tooling developed for blogs, you are right, as technical and scientific writing overlap. Some popular libraries for documentation, e.g. MkDocs (Python) or Docusaurus (Javascript) could be tweaked and used for blogging, and Quarto launched last year as an open-source scientific and technical publishing system.

Given my investment in building tools and services around science blogging, it should not come as a surprise that I am consolidating the tooling for the documentation of my open-source software projects. Three weeks ago I relaunched one of my two blogs using Quarto. This week I am relaunching the following documentation sites also using the Quarto:

• Commonmeta - a metadata standard for scholarly metadata
• Commonmeta-py - a Python implementation of commonmeta
• Commonmeta-ruby - a Ruby implementation of commonmeta
• Rogue Scholar - an archive for scholarly blog posts

Previously, the documentation for these libraries and services used MkDocs and Nextra (using React, Next.js, and MDX) with markdown files and YAML front matter. The commonmeta-py documentation also included several Jupyter notebooks, which are nicely supported by Quarto out of the box:

There is still a lot of work to do to improve the documentation – always the hardest part. I wrote a new page about using Rogue Scholar with a Wordpress blog and plan to document my experience with other popular blogging platforms. The commonmeta-ruby documentation is still rudimentary, and I have started to experiment with Jupyter notebooks written in Ruby. The OpenAPI documentation of the Rogue Scholar API is not integrated into the Quarto Rogue Scholar documentation yet, and I am evaluating Quartodoc to automate the documentation of Python methods and classes similar to what Sphinx is providing.

One feature that Quarto has in common with other open-source documentation systems is that the source code, including the markdown files, is hosted in a public code repository, so questions, comments, or suggested changes are easy:

Please use this functionality if you want to help improve the documentation, or if you find functionalities that should be documented better.

References

Fenner, M. (2023). The programmable blog. https://doi.org/10.53731/ch2e1-1cm64