Google Season of Docs/2021/Case Study

Season of Docs Case Study for 2021

Title

Organization: BRL-CAD

Description: BRL-CAD is a powerful cross-platform solid modeling system for 3D computer-aided design and graphic visualization. Currently standing at more than a million lines of code and hundreds of staff-years investment, BRL-CAD has nearly 40 years development history (since 1979) and is in production use by more than 2000 organizations. BRL-CAD is represented, used, and developed by a collective of industry, academia, and government participants from all over the world.

Authors: Sean Morrison <brlcad>

Problem Statement

In all, BRL-CAD has more than a million words of documentation across hundreds of manual pages, dozens of tutorials, hundreds of wiki pages, dozens of technical papers, and other resources. There are literally thousands of features created over decades of development.

This project attempts to modernize our infrastructure with this effort migrating the bulk of BRL-CAD's existing documentation from the Docbook XML format to AsciiDoc in Antora. This is a first-step towards improving the documentation management by consolidating onto a system that is more accessible and maintainable, while preserving our ability to "compile" documentation into HTML, PDF, and other formats.

Proposal Abstract

Our organization focus for the 2021 Season of Docs entailed migrating BRL-CAD's core documentation infrastructure off of Docbook XML. For many years, BRL-CAD has utilized Docbook XML for primary documentation management but with tooling complexity, documentation support limitations, and authoring challenges. XML tools are available but require custom integration and custom maintenance. Docbook XML as a format (with or without XSLT) is not well-suited to certain types of documents (e.g., presentations, flyers, quick reference sheets, or documents with very specific formatting). It's also not as common or familiar as simpler text-based formats (e.g., Asciidoc, Markdown, etc) that have since become popular and commonplace.

As such, this project involved setting up a new system in order to better understand modern available options and migrate a significant portion of documentation to said system.

Original organization proposal is available here.

Project Description

Creating the proposal

We had already identified documentation infrastructure as a potential project several years ago, recognizing that it was tedious and hard for contributors to work on BRL-CAD's documentation. On multiple occasions, we had contributors join BRL-CAD and attempt to work on documentation. We were even successful getting a few translations of our 1-page "About BRL-CAD" documentation, but the Docbook XML format was demonstrably a very significant challenge for contributors. As such, evaluating new doc infrastructure has been on our forefront attention -- particularly any solutions with the potential for *round-trip* editing while still being manageable in a revision control repository. Round-trip editing proved to be a specific challenge for Docbook XML as online editing options are limited.

A call for feedback was put out on our Zulip chat and discussed regularly amongst the community. There was much discussion and preliminary research on Antora vs Docusaurus vs MkDocs vs other solutions. Ultimately, an executive decision was made to trial a conversion to Antora as it appeared to offer the most alignment and compatibility with Docbook XML, and this project idea was the result.

Budget

Project budget estimation was very straightforward. As the project was constrained to documents already under revision control in Docbook XML format, we already has prior experience with their approximate conversion costs and level of effort. By counting the number of documents, document complexity, number of pages, and taking timeline into consideration, we arrived at an estimate of 3-4 months of full-time effort. Depending on the person's background and skills would determine if it was more or less.

We did not encounter any unexpected expenses except for time and resourcing required to set up banking accounts for paying our writer. Account establishment took considerably more time than was expected resulting in delays and frustration. This is elaborated on more in the below Analysis section.

Participants

This project was principally worked on by our writer, Dashamir Hoxha.

He found us.

Timeline

We we anticipated the project would require 3-4 months of near full-time effort. Our writer was consistently ahead of schedule such that he completed the majority scope in a little under 2.5 months time. He then invested another month expanding scope to work on our wiki and gallery conversion, which were not in Docbook XML format.

Results

The conversion work is still pending brlcad.org integration as it's a big change, but our main docs are staged publicly at: https://brl-cad.fs.al/

Our docs were converted from Docbook, Mediawiki, and Piwigo for our main docs, wiki docs, and gallery respectively. All three are now available on our GitHub repo: https://github.com/BRL-CAD/brlcad-docs https://github.com/BRL-CAD/wiki https://github.com/BRL-CAD/gallery

Metrics

Measuring success was (initially) a simple function of percent documentation converted to AsciiDoc and deployed to Antora. At present, there are 505 .xml documents in doc/docbook of the repository that require conversion. For the project to be considered successful, we identified (somewhat arbitrarily but based on need) a requirement of 90% of the existing Docbook files to be fully converted to AsciiDoc, imported to Antora, and deployed online.

Our writer was adept at revision control and documentation systems, so he was able to establish repositories on GitHub with complete transparency on progress being made. Updates were shared over Zulip as well.

Analysis

The project was a resounding success. We had identified approximately 505 Docbook XML files for conversion. Our result is 674 Asciidoc files as well as two more repositories of conversion.

As for SoD itself ...

The application process was a little confusing given status and uploads are not tracked through a web app / interface as they are with the Summer of Code. We had to repeatedly go back to the program documentation to see if there was anything we overlooked or an action we missed, and there was always a bit of uncertainty.

The documentation, templates, and examples from Google are excellent, but we found it to be a very manual process. It would be helpful if there were a login portal for administrators that is used to view org submission status, see upcoming deadlines, manage writer applications, etc, as is done for GSoC. We realize SoD is different and targets different individuals, but the benefits of a personalized dashboard would have greatly helped reduce some uncertainties.

While we loved the idea and potential, and think Open Collective is a great resource, it was our biggest hurdle. It was excessively complex, confusing, and ultimately contributed to a loss of trust with our writer. It took months to resolve banking issues. We didn't know it would at the time and resolution always seemed a week or two away, but he eventually (and understandably) questioned why weeks would pass without payment. Ultimately, we had to establish a new business banking account that would work internationally.

If our writer had been okay with a Paypal transfer or if we already had an international bank account established or if our org were comfortable entering into a legal relationship with an unknown fiscal sponsor on Open Collective, none of this would have been a problem, but that is hindsight knowledge specific to our participant...

I think it would be a great improvement if payment could be issued from Google to writers directly, so orgs are not caught in the middle of international payment system rules and regulations. It would also help avoid multiple exchange rate / transfer fees.