Open Source Docs as Code
Channel: The ASF
Date: 2020-10-17

Open Source Docs as Code
Cassandra Targett

A presentation from ApacheCon @Home 2020
https://apachecon.com/acah2020/

This talk will review the Lucene community's experiences maintaining Solr documentation in the same way we maintain code. Prior to 2016, the Solr Reference Guide was only in Confluence (cwiki). Despite community agreement that docs are important, editing them was a separate process that was easy to put off. That put a burden on a few committers to update the content for each new release, and frequently each version's Guide was not complete for 2-3 months after a release was announced. In 2016 we decided to integrate the documentation with our source code. We converted Confluence pages to AsciiDoc files and started generating static HTML pages hosted in our main website. These changes allowed committers to update documentation as they changed the code. In an open source project where everyone is a volunteer and there are possibly only 1-2 people who understand any feature, this has been an incredibly empowering change. Today committer maintenance of docs is high enough that the Guide requires very little effort to prepare for publication. All Release Managers can publish it as part of the release process, reducing the burden on the few who knew their way around the old system. This engagement means the Guide can evolve quickly as community needs change. In this talk I'll share how we made these choices, the content and build tools we use, and how other projects can make updating docs a natural part of the code change process.

Cassandra has 20 years experience in search and knowledge management. She has been an Apache Lucene committer since 2013 and a member of the PMC since 2016. As Director of Engineering at Lucidworks, she manages the day-to-day work of the Solr development team.