Editing Google Season of Docs/2021/Case Study

== Migrate BRL-CAD's Documentation Infrastructure ==

Organization: BRL-CAD

Case Study Author: Sean Morrison <brlcad>

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.

This project attempts to modernize BRL-CAD's infrastructure with this specific effort initiating an exploratory migration of BRL-CAD's existing documentation from the Docbook XML format to AsciiDoc in Antora.  This is a first-step towards improving documentation management by consolidating onto a system that is more accessible and maintainable while also preserving our ability to "compile" documentation into HTML, PDF, and other formats. It is also a step towards supporting bidirectional documentation authoring and editing of documents for documents online and under revision-control. 

== 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 requiring tooling customization, imposing documentation support limitations, and presenting significant authoring challenges.  Docbook XML tools are available and robust, but have required custom integration and custom maintenance.  Docbook XML as a format (with or without XSLT) is rich and complex, but still 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 to being migration of a significant portion of BRL-CAD's documentation to a system addressing one or more of the challenges faced with Docbook XML.  Anotora was proposed as a potential solution worht exploring in significant detail given Asciidoc's strong alignment, richness, and compatibility with Docbook as well as simple text formatting and ability to support manual pages, presentations, and other document types.

===Creating the proposal===

The BRL-CAD development team had already identified documentation infrastructure as a potential project several years ago, generally recognizing that it was tedious and non-trivial for most contributors to work on BRL-CAD documentation.  On multiple occasions, new contributors to BRL-CAD would attempt to work on documentation, only to disengage due in part to the infrastructure complexity.  Even the development team struggled at times to migrate documentation in other formats to Docbook XML given the verbosity, complexity, and lack of editing support tools.  The custom integration of Docbook XML within the build system was (and is) very powerful and robust, but cumbersome to edit.  Hierarchy was (and is) rigidly coupled to the build system making restructuring maintenance very costly (hence avoided).  

 

A call for feedback was put out on our Zulip chat and potential discussed amongst community members.  Early discussion and preliminary research was invested 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 initiation was the result.

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 involved.  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, approximately.  Several documents were manually converted to validate estimation intuition.  

 

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

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

 

 

 

With a formal agreement and direct fiscal responsibility, interactions with the writer were less informal than was typical under GSoC and other mentoring programs.  We also learned the need to be more transparent in our discussions about payment systems, account setup, and payment methods.  We also learned that our organization has not been very resilient to the effects of covid on our community and that our communication systems suffered as individuals became overworked, stressed, and with multiple competing obligations.  We learned that we need to be considerably more proactive, ideally measuring metrics along the way so we can adapt more effectively.  

We we anticipated the project would require 3-4 months of near full-time effort.  As mentioned, we scoped this project to the size of our existing Docbook XML files consisting of approximately 505 documents.  After converting several by hand while tracking time, a shorter or longer SoD timeline became supportable.

 

Our writer was consistently ahead of schedule such that he completed the majority scope in a little under 2.5 months time.  He came to the project with significant Docbook and documentation system experience, so he adapted and got set up quickly.  He then invested another month expanding his tasks to work on our wiki and gallery conversion, which were not in Docbook XML format.  Those conversions came as a very welcome but surprise.

 

As for dates, we set a preliminary start date to coincide with the start of SoD and an estimated end date tentatively and approximately at 3-4 monhths later.  Since our writer remained consistently ahead of schedule, he was able to complete the work within 3 months even with his addition of wiki and gallery tasking.

The conversion work is still pending brlcad.org integration and final review as it's a big corpus of changes, but the new documentation system is staged publicly at:

 

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, representing a long migration oprimicas

Measuring success was (initially) a simple function of percent documentation converted to Asciidoc and deployed to Antora.  At project start, there were precisely 505 Docbook XML documents in our doc/docbook folder of the repository that required 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 ended up creating approximately 674 Asciidoc documents in the brlcad-docs repository.  This far exceeded our success criteria.  No additional metrics or criteria were added.

As for our writer's efforts: 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.  The BRL-CAD "wiki" repository included a conversion of 624 of our website MediaWiki pages from Mediawiki markup to Markdown format.

There were 41 people that interacted on our Zulip Season of Docs stream, but 1-on-1 interactions with our writer were not at the level we typically want to see for other mentoring programs (e.g., GSoC).  We typically like to see several messages per day, throughout the day, and interactions were typically several messages per week instead.  As our writer was doing a phenomenal job making visible progress independently and without roadblocks, developer attention shifted. Several developers, myself included, found themselves overwhelmed with too many concurrent responsibilities. We did not adapt well to our staffing changes and communication challenges.

As for the SoD program:  the application process was a little confusing this year, more so than in previous years, in part due to changes.  Status and uploads are not tracked through a web app / interface as they are with the Summer of Code, so that also contributed to confusion.  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.