Framework for architecting technical documentation
BSSw Fellow Peter K. G. Williams aims to teach scientific software developers how to create better documentation. For many, the word evokes a feeling of guilt, or dread. Have I written enough? Is what I’ve written any good? While these questions might occur to any kind of developer, scientific software raises some additional ones: How do I integrate my documentation with the academic literature? How do I teach users about the links between physics concepts and code? How do I get professional credit for this work? Peter is constructing an online learning resource aiming to answer these sorts of questions: documentation about documentation. The resource will present a conceptual framework for architecting technical documentation, strategies for creating effective documentation, and specific techniques for implementing those strategies. The goal of the year-long project is to deliver an end-to-end resource: one equipping scientific software developers with the basic conceptual and authoring tools they need to document typical projects satisfactorily.
Peter is the technical lead for the Minor Planet Center, based at the Center for Astrophysics | Harvard & Smithsonian. Along with a research background in time-domain observational radio astronomy, he has extensive experience in open-source software development, and he is preoccupied with all of the ways in which information technology could be revolutionizing science---but isn't yet.
