Documentation

I handled developer relations for an open source project, writing documentation, a contributor's guide, and a newsletter.

View Docs Hub

Screenshot of the developer documentation hub — The documentation hub includes all of our technical docs for system administrators, contributors and third-party developers.

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.

Screenshot of the request lifecycle diagram — I made a diagram to help visualise the request lifecycle.

When we introduced a REST API, I adopted json-schema as a simple mechanism to describe our data objects.

Example entity schema

{
  "title": "Publication",
  "description": "A published version of a submission.",
  "properties": {
    "id": {
      "type": "integer",
      "readOnly": true
    },
    "title": {
      "type": "string",
      "multilingual": true
    },
    "path": {
      "type": "string",
      "validation": [
        "max:64",
        "alphanum"
      ]
    }
  }
}

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.

Screenshot of the REST API docs — Human-readable documentation for our REST API, with response payloads that are derived directly from the application's entity schemas.

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.

Screenshot of PKP's contributor's guide — Our contributor's guide helped new members of our community understand how we worked and — hopefully — made them feel more welcome.

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.

Screenshot of code review section of contributor's guide — The best code reviews are opportunities for learning. No assholes, please.

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.