05-12, 12:00–12:30 (Europe/Paris), Louis Armand 2
JupyterHub has a range of documentation that covers both developer and user audiences in order to help them deploy, maintain, and use their own instance of a JupyterHub. The success of an open source software project to (i) be adopted by users, and (ii) receive meaningful contributions relies heavily on the quality, navigability and accessibility of documentation so that users and developers have all the information they need to achieve what they want to do.
A framework for organising technical documentation has arisen called Diátaxis. It takes a systematic approach to understanding user requirements of documentation throughout the lifecycle of interaction with a product and posits that different user needs require different approaches in creation of the documentation, as well as a layout to navigate these different “modes” of documentation.
Between December 2022 and March 2023, the JupyterHub project will be participating in the December 2022 round of Outreachy internships with the aim of improving its documentation. The project focuses on refactoring the documentation for the JupyterHub package. As the intern in charge of this process, my work began by performing a review of the present documentation, categorising these into the diataxis framework, and then restructuring the documentation files in the repository. Once the documentation is transformed into this framework, it will be easier to identify missing and unclear documentation (those that were difficult to categorise). Subsequently, the JupyterHub team can curate resources that can fill the gaps and improve documentation that is not specific enough.
This undertaking is not without its challenges, joys, and lessons, which can be extrapolated to other open-source documentation projects. The proposed talk will focus on highlighting these areas from the point of view of the JypyterHub Outreachy intern as well as their lead mentor. Specifically, it will seek to cover three main points within the allocated talk time:
- What is the importance of well-written and -structured documentation to an open-source project and to JupyterHub, specifically?
- What is the Diataxis framework and why did JupyterHub select to use it to restructure its documentation?
- What lessons can other open-source projects learn from JupyterHub’s experience to make clear and well-structured documentation?
The talk targets anyone who authors or contributes to open-source software documentation, including technical writers and team leads. The audience can be working with any programming language but should have intermediate knowledge of technical writing practices, including what it entails and some of the tools used.
Allan Wasega is a budding technical writer and researcher based in Nairobi, Kenya. A recent Computer Science graduate, Allan has served as a technical writer with Tingle Software, a Nairobi-based software company where he has been helping to create user and technical documentation. As one of the 64 accepted interns in the December 2022 cohort of Outreachy interns, Allan has been working on restructuring JupyterHub’s documentation using the Diataxis framework. Since 2019, Allan has also been a mentor at KamiLimu, a structured mentorship program for students pursuing technology-aligned courses in institutions of higher learning in Kenya. Besides mentorship and writing, Allan loves reading books and listening to podcasts, especially those that touch on philosophy, uncertainty, and risk. Connect further with Allan on twitter: @alwasega.
Sarah Gibson is an Open Source Infrastructure Engineer at 2i2c, an open source contributor and advocate. She holds more than two years of experience as a Research Engineer at a national institute for data science and artificial intelligence, as well as holding a core contributor role in the open source projects Binder, JupyterHub, and the Turing Way. Sarah is passionate about working with domain experts to leverage cloud computing in order to accelerate cutting-edge, data-intensive research and disseminating the results in an open, reproducible and reusable manner. Sarah holds a Fellowship with the Software Sustainability Institute and advocates for best software practices in research. She is a member of the mybinder.org operating team and maintains infrastructure supporting a global community in sharing reproducible computational environments. She has also mentored projects through two cohorts of the Open Life Science programme, imparting lived experience of her skills participating and leading in open science projects.