Enabling Open Science through Research Code: Insights from Episode 4 - Documentation for Research Code

Research Software Engineering Open Science Coding Community Building Experience Blog

This is a blog sharing insights from Episode 4 of the Community Conversation series ‘Enabling Open Science Through Research Code’.

Anelda van der Walt, Jyoti Bhogal https://github.com/jyoti-bhogal
02-20-2025
Episode 4 banner

Imagine you’ve spent months crafting a complex research software tool, refining algorithms, and running countless simulations. It works brilliantly—but then, six months later, you revisit the code and… you’re lost. Sounds familiar? You’re not alone. Experts shared their experiences and strategies for writing good documentation in the fourth episode of the Research Software Community Conversations Series titled Enabling Open Science through Research Code. Here’s what we learned from our participants and insightful panellists:

📌 Why Documentation is Essential

🚀 Boosts Reproducibility: Research software often accompanies papers, but results can be difficult to replicate without documentation. As Jenny pointed out, in fluid dynamics research, well-documented simulation codes gained more adoption than poorly documented alternatives.

🤝 Facilitates Collaboration: Well-documented projects attract more contributors and streamline knowledge transfer. Joel shared his experience in the rOpenSci community, where clear documentation allowed him to take over and improve an existing R package without needing direct input from the original creator.

⏳ Enhances Longevity: Code without documentation quickly becomes unusable—even by its original authors! Mthetho described how well-documented software in weather forecasting led to unexpected collaborations with the South African Weather Service and Ethiopian researchers.

🔓 Promotes Open Science: Accessible research software fosters innovation and inclusion worldwide. Jenny emphasised that accessible documentation enables wider adoption of tools, making scientific computing more democratic.

🔥 Common Challenges & Solutions

⏰ Time Constraints → Write minimal but clear documentation as you code. Joel suggested that legible code, such as meaningful variable names instead of “x” or “dat”, is itself a form of documentation that is even better than comments.

🧩 Lack of Standardisation → Use templates and structured frameworks. Mthetho mentioned that clear, structured guides helped non-computational scientists successfully use OpenFOAM in unexpected fields like environmental science.

🎯 Technical vs. User Documentation → Engage users in documentation efforts for clarity. Jenny highlighted the role of community-driven documentation efforts, such as hackathons, to improve usability.

🛠 Best Practices for Better Documentation

✍️ 1. Write as You Code

Waiting until the end leads to missing details. Add inline comments and README files while developing. Joel emphasised that tools like RMarkdown (and its successor, Quarto) can be used for literate programming—thereby ensuring that the results of code are automatically generated alongside their description.

🔄 2. Differentiate Documentation Types

✔ User-facing documentation: How to install, use, and troubleshoot.

✔ Developer-facing documentation: Comments, API references, contribution guides.

📚 3. Use the Right Tools

📄 Markdown & Jupyter Notebooks – Combine narrative and code.

📝 Quarto & R Markdown – For structured research outputs.

📘 Sphinx & MIST – Python-based documentation frameworks.

🌐 GitHub Wikis & Pages – Host documentation openly.

🤖 AI-based tools (e.g., Cursor, Copilot) – Assist with documentation (but always review!).

🤝 4. Community & Collaboration Matter

💡 Participate in documentation hackathons. Jenny shared how Project Pythia’s hackathons provided a structured way to improve documentation in geospatial science. 🌍 Join communities like Project Pythia, The Carpentries, and Write the Docs.

💰 5. Advocate for Funding & Policy Support

📢 Push for documentation funding in grant proposals.

🏛 Engage with funders to integrate documentation into open science policies.

🚀 Future of Documentation: AI & Automation

🤖 Automated Documentation: AI tools generate initial drafts, saving researchers time. However, while helpful, AI-assisted documentation should always be reviewed for accuracy.

🌍 AI for Translation: Helps make documentation accessible in multiple languages, fostering global inclusivity. Anelda highlighted how AI tools might support research documentation in multilingual communities in the future. For now, we still need a human-in-the-loop translator for translation efforts. Especially for low-resourced languages.

⚠️ Caution Needed: AI-generated content must be reviewed for accuracy and ethical considerations. Jenny raised concerns about biases in AI and the environmental impact of large-scale machine learning models.

🎯 Final Thoughts: Make Documentation a Priority

Great research code deserves great documentation. It makes work reproducible, fosters collaboration, and ensures that software remains usable long after its creator has moved on. By embracing best practices and community support, we can all contribute to a culture where documentation is seen not as a burden—but as a fundamental part of open science.

📢 Explore More:

Access our Resource Sheet, which contains numerous valuable resources shared by the panellists, facilitators, and participants.

View the session recording on YouTube.

The first draft of this blog post was created with ChatGPT from the edited video transcript.

Looking Ahead

The next episode in the series, “Testing Research Code” will take place on February 20, 2025, at 08:30 UTC. Be sure to register here and join the conversation!

For those who missed Episode 4, a resources sheet with tips and the session recording on YouTube is available. This series is an excellent opportunity to learn, connect, and grow as we work together to enable open science - one line of code at a time.

This meetup series is a collaboration between Talarify, RSSE Africa, RSE Asia, AREN, and ReSA.

Learn More About Us

For more information and to join upcoming events, visit:

RSSE Africa

RSE Asia

AREN

ReSA

Citation

For attribution, please cite this work as

Bhogal (2025, Feb. 20). RSE Asia Association: Enabling Open Science through Research Code: Insights from Episode 4 - Documentation for Research Code. Retrieved from https://rse-asia.github.io/RSE_Asia/

BibTeX citation

@misc{bhogal2025enabling,
  author = {Bhogal, Anelda van der Walt, Jyoti},
  title = {RSE Asia Association: Enabling Open Science through Research Code: Insights from Episode 4 - Documentation for Research Code},
  url = {https://rse-asia.github.io/RSE_Asia/},
  year = {2025}
}

This website is built using the R package distill.

RSE Asia Association - copyright