Documenting known unknowns


This talk explores the challenges associated with documenting a project with a very difficult subject and having an audience with vastly different backgrounds. I started a project two years ago to document a database query language that was invented to work with genomic databases. It is an esoteric subject where the knowledge was very much in the heads of a small number of people, but needed to be accessible to an audience including geneticists, software engineers, bioinformaticians and hospital clinicians. We use a mixture of Sphinx (with some adaptations) to bring in contributions from people working on the language and the project has grown to include contributors from all the backgrounds I mention here. By treating the documentation like a code project, we created a process we can work with, but this talk is really about the process of translating information within a single language and between domains and how to make information accessible without sacrificing meaning.

  • Conference: Write the Docs PRAGUE
  • Year: 2019

About the speaker

Alison MacNeil