From Code to Clarity: What Makes Good Docs?

User/Developer Experience Webinars feature speakers who highlight best practices and challenges for usable scientific software. Have a suggestion for a future meeting? Use this Google form to propose ideas.

Effective documentation is crucial for the success of any software project, but it’s especially vital in the world of academic and scientific research. In this talk, leaders from The Good Docs Project will explain why documentation matters, including helping users quickly onboard, streamlining troubleshooting efforts, and accelerating problem-solving.

They will then break down the core principles that set truly great documentation apart, including being task-focused, well-structured, and written from the user’s point of view. We’ll also leave you with some practical strategies for integrating documentation seamlessly into your existing development workflow and processes using the docs-as-code framework. This will empower you and your colleagues to maintain high-quality docs alongside your code, without the extra overhead.

Whether you’re new to writing documentation or looking for ways to enhance your existing practices, this talk will empower you to take your software documentation to the next level.

Presenters

• Alyssa Rock (The Good Docs Project)
• AlyCarrie Wattula (The Good Docs Project)

Organizer

• Johanna (Hannah) Cohoon (Lawrence Berkeley National Lab)

Presenter bio

Alyssa Rock has been a technical writer for more than a decade with a specialty in writing for open source software. Currently, she works as a technical writer for Cribl, the data engine for IT and security. When she’s not at work, she’s usually volunteering with The Good Docs Project where community members from every part of the world come together to improve documentation in open source software and beyond.

Organizer bio

Johanna (Hannah) Cohoon is a User Experience Researcher at LBNL, seeking to create more rewarding and impactful careers for research software engineers and more efficient and enjoyable experiences for users. She has focused on studying and facilitating open source development, open science practices, and data intensive workflows. Hannah earned her PhD from the University of Texas at Austin. Hannah leads the CASS UDX working group.