Documentation
When I joined the Public Knowledge Project, I struggled to understand how their software was structured. Most of the code had been written by two or three developers, and they relied heavily on a shared understanding of the codebase. A class reference document was available, but there was no documentation which described the overall architecture or the choices they had made when designing the application.
As our team grew, I was given a little time to write the documentation that I had wished existed when I started. The result was our main developer documentation, a high-level orientation to the application's architecture. It covered the request lifecycle, routing, authentication and authorization, request handlers, and how we expressed domain concepts as entities and read and wrote them to the data store.
When we introduced a REST API, I adopted json-schema
as a simple mechanism to describe our data objects.
This allowed us to automate some of the validation and read/write operations in our data access objects. The upside was that the entity schemas could be reused in OpenAPI/Swagger, a machine-readable format commonly used to describe REST APIs. From there, it was pretty easy to generate API documentation using redoc
.
As our community grew, we had to find better ways to triage issues and review pull requests. I wrote a contributor's guide which described how to report bugs and propose new features. It also outlined our code style and instructed developers how they should open a pull request.
The part of the contributor's guide that I am most proud of is the section where we describe what to expect from a code review. At PKP, we worked hard to maintain a welcoming community. This section of the guide was written to convey how important it was for us to minimize bike-shedding and other forms of toxic behaviour common in open source tech communities.
Finally, I started and wrote a bimonthly newsletter for developers. The newsletter sought to reach a segment of our community that wasn't active in GitHub issues or our community forum. I shared regular updates on the development team's work, as well as interesting work from the community.
The documentation that I wrote for PKP will probably prove to be some of the most enduring work from my time with the organisation. The number of third-party developers, and the complexity of their customizations, grew a lot in recent years. And best of all, we found that new developers were able to get up to speed quickly and start contributing on difficult issues shortly after joining the team.