Awarded a 2025 Better Scientific Software Fellowship

2024 December 18

I’m delighted to be able to share that I’ve been awarded one of five 2025 Better Scientific Software Fellowships by the Better Scientific Software (BSSw) community. It’s very exciting to have BSSw support my efforts to deliver better technical documentation to the world!

The BSSw Fellowship Program describes itself as giving “recognition and funding to leaders and advocates of high-quality scientific software.” There’s an annual competition on the basis of a mercifully brief written application, with fellows being awarded $25,000 to conduct a project that promotes better scientific software, in some fashion.

Here’s my project proposal, exactly as written in my application:

As a BSSw Fellow I would 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? I would construct an online learning resource aiming to answer these sorts of questions: documentation about documentation. It would present a conceptual framework for architecting technical documentation, strategies for creating effective documentation, and specific techniques for implementing those strategies. The content would build on my experience creating documentation for projects such as the HERA Librarian, DASCH, WorldWide Telescope, and Tectonic. For instance, while the Diátaxis system (https://diataxis.fr/) provides a valuable high-level framework for documentation design, it does not mention elements such as landing pages and finding aids, which I have found to be important in my projects. Diátaxis also (intentionally) does not provide guidance on specific tools to adopt. My resource would provide a set of suggested tools and templates supporting the needs of scientific software authors, such as cross-references to the academic literature and high-quality mathematics. Development of the resource would be iterative, involving community feedback and A/B testing of different documentation strategies within the resource itself. To enable this, I would seek to build community around the project through targeted outreach and conference talks. The scope of the project would be delivery of an end-to-end resource: one equipping scientific software developers with the basic conceptual and authoring tools they need to document typical projects satisfactorily.

Whenever I’m writing a proposal I try to ask myself, “Will I be happy if this proposal is accepted and I actually have to do this?” In this case, the answer is an emphatic “Yes!” If you’ve been reading this blog regularly you’ve probably noticed that I regularly have documentation on my mind and fixate on software tools for writing like Upwelling (see also Jacquard, which I haven’t actually written about yet!), PubPub (ditto!), and of course TeX and Tectonic; you can think of Diátaxis as a tool for writing as well. It’s going to be great to have some financial support that allows me to spend part of my workdays actually building something relevant to this space.

I can already foresee one challenge, though. The BSSw Fellowship is about helping other people but it is emphatically not about building novel tools ­— no “research” allowed. And more and more, I feel like every digital documentation tool that I’ve ever seen is only a partial solution at best; I see so much potential to do better. It’s going to take a little bit of discipline to stay focused on helping people right now, rather than getting derailed thinking about what might be. I’m hopeful that maybe I can find some time and support to work on that side of the equation, too, although the next year is going to be a busy one for me (even moreso than usual, that is).

Regardless, you can expect at least a few updates about this project over the next year-and-change. Based on other things that I will be keeping me busy, I don’t expect to ramp up my BSSwF effort until later in 2025, but I’m excited to get going!