Part 1: improve the interoperability of scientific documentation¶

This work is something that we’ve been doing as a side project for some time now. We have an extension to Sphinx that we call sphinx-hoverxref. It provides hovering tooltips for Sphinx projects when hover over a link. You might be familiar with this functionality on GitHub or Wikipedia – this project adds that functionality to any project hosted on Read the Docs. You can see a live demo on a fork of the Python documentation.

The goal of the grant will be to expand this functionality by doing a few things:

• Improving and documenting the backend Embed API on Read the Docs, allowing documentation content to be embedded anywhere on the web.

• Building a JavaScript client for the Embed API, which includes tooltips showing the content on any website.

• Integrating this JS client and backend API together in a new version of sphinx-hoverxref.

• Extending sphinx-hoverxref to work across multiple Read the Docs sites, allowing content hovers across the entire scientific documentation ecosystem.

• If time allows, also extending the backend Embed API to support Sphinx documentation hosted outside of Read the Docs, allowing even more interoperability between documentation.

We are planning to contract a frontend developer to help with this work. The Python work will likely be carried out by our existing team, funded via the grant. This is because of the complexities involved with the Read the Docs and Sphinx integration, it will be more cost effective to have people already familiar with the codebases on these tasks.

Part 2: Advocacy work around documentation in the scientific community¶

We know that documentation is a pain point for scientific projects. There is a lack of resources in the community, and we feel that we can be a central clearing house for better documentation tutorials and best practices. This part of the funding will be about growing appreciation and knowledge of documentation in the scientific community in general, and advocating for time to be spent on crafting good documentation with the best tooling.

Part of this work would be letting people know about the work in Part 1, promoting the tooling to make better documentation in the Scientific Python ecosystem. Beyond that, we will also promote tutorials and best practices around documentation for Scientific users, leading to more resources being available and better documentation in the community.

The high-level roadmap for this part of the grant is:

• Improve documentation and promote the work in Part 1.

• Adapt the Guides section of the Read the Docs documentation into a more full-featured Education section, along with standardizing and editing all existing guides.

• Expand our existing Sphinx Tutorial, hopefully adding it upstream to Sphinx as the official tutorial

• Write additional documentation guides focused on the scientific community, based on feedback from people in the community. This will likely include tutorials on integrating Jupyter with Sphinx, Jupyterbook, and other pain points that users have.

• If time allows, we would also love to work on curating some of the documentation resources at Write the Docs, specifically topics that are relevant to scientific projects.

As part of this work, we plan to contract someone in a technical writer/developer evangelist role. Someone with knowledge of the scientific community would be a great benefit, given that we plan to seek feedback from many scientific projects on the priority of tasks we work on.

Looking forward¶

We are starting to look for contractors who would be a good fit for the work. People who care about documentation and are already connected with the scientific community are a big plus. We hope to post proper job descriptions for these roles in the near future, but wanted to note that we’re looking in our initial announcement.

This is the largest grant that we’ve ever received, and we are working hard to make sure it’s successful. We appreciate the trust that the Chan Zuckerberg Initiative has placed in us, and we will work hard to make sure the results of this grant will be adopted across the scientific ecosystem.

If you want to keep up to date with this work, you can follow along on GitHub or subscribe to our blog for updates.