Google Season of Docs/Proposal
This is our 2021 proposal to the Google Season of Docs. Please direct any questions or comments to devs@brlcad.org
Contents
Migrate BRL-CAD's Documentation Infrastructure
About BRL-CAD
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 around the world. BRL-CAD is represented, used, and developed by a collective of industry, academia, and government participants from all over the world.
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. BRL-CAD's set of current manuals, guides, tutorials, and other documentation are listed on our website wiki and included in our repository].
About Our Doc Infrastructure
| Technologies | Difficulty | Contacts | |
|---|---|---|---|
| BRL-CAD has extensive documentation infrastructure using Docbook XML whereby we "compile" them into HTML, PDF, and other formats. This approach helps ensure docs remain up-to-date, without syntax/structure errors, and allows the documentation to be composed and reused in different ways (e.g., an tutorial on some topic might get embedded as an appendix in one document or a chapter to another). That said, the underlying format is tedious to write and hard for contributors. We'd like to migrate to a newer system like Antora or Docusaurus or MkDocs, converting everything over while still retaining build system integration.
References:
|
Docbook XML, AsciiDoc, Markdown, Antora | Medium | morrison, rossberg, yapp |
Scope of the Project
This project attempts to modernize our infrastructure migrating existing documentation from Docbook XML to AsciiDoc in Antora.
What is in scope?
The minimum scope of the project is migrating our existing Docbook XML docs in our repository.
What is not in scope?
There are extensive docs not in Docbook XML format in our repository, on the website wiki, in other formats, and in other files that are desirable and may also be migrated (e.g., for testing purposes), but they are secondary priority and need not be considered in scope.
We estimate that this project will take 3 months to complete. We have three mentors willing to directly help with this effort and that have committed to supporting the project.
Measuring Success
As this project centers around migrating documentation, measuring success is a simple function of percent converted.
