Documentation in open source software

Documentation is often the first stop for new users with an open source software project, including how to use it. But in many open source projects, documentation isn't the top priority. Developers usually want to work on software, not write about it.

Writing documentation can be a great way to contribute to your favorite open source software project - and gain some experience at the same time. To celebrate the National Day on Writing on October 20, we met with several contributors from different open source software projects for a virtual roundtable discussion, to talk about how people can contribute to open source documentation, and what skills they need to get started.

What open source project do you contribute to?

Bekah: Hey! I'm Bekah, and I'm a career changer. I spent ten years teaching college English before coming into tech a little over five years ago. I started maintaining my first project four years ago during Hacktoberfest. Right now, I'm the Developer Experience Lead at OpenSauced, where we surface open source insights to validate and support open source projects, teams, contributors, and maintainers. I spend a lot of time talking to maintainers about their challenges and maintaining our courses, docs, and community projects.

Ruqaiya: This is Ruqaiya Sattar from Pakistan. It was 2023 when I learned about an Outreachy internship about open source software. I applied and was selected for the internship on my first try. That was how I got involved with open source software projects and the Mboalab project.

John: Hi all, my name is John Ellis and I'm newer to open source over the course of my coding career. I am currently a civic tech volunteer contributing to the Code with Carolinas mission to use technology to help people living in North and South Carolina. We utilize Codeberg for our Git needs for a website, and two projects we are actively working on for national initiatives; National Zoning Atlas and Open Sidewalks.

What kinds of documentation does an open source project need to have?

Bekah: In our Becoming a Maintainer Course, we talk a lot about this. I like to think of documentation as setting up contributors and maintainers for success. You need to answer the questions you'll frequently have, and provide a clear path for communication and contribution.

As part of that, having a Readme file, contributing guide, code of conduct, and license are incredibly important. Depending on the project, including a quickstart guide in your Readme can be a great way to reduce friction for new contributors, but it's always important to include information about running your project to get users started.

Ruqaiya: Any open source project must have a Readme, contribution.md, installation steps, a file that includes the purpose of the project and history behind it and also what future goals it has. I'd also add wiki guides, installation guides if additional needs like how to run or set up on different platforms, and screenshots of running output of the app too.

John: Overall, the Readme is important because it's the first thing someone sees when going to the documentation and this serves as the "triage" area. At its core, it should highlight what the project is, a "contributing" section, how to interact with the repository, and information about Licenses or Source/Ethical/Data Governance Considerations.

Not all documentation can go here so it's helpful to have something like a wiki which acts as a Single Source of Truth for the repository with more detailed guides and how-tos. It's also important to consider - as important as separate documentation is - it's also very beneficial to include them in the project scripts as well through headers, doc strings, comments.

Documentation serves lots of reasons from continuity, planning, and for regulation potential and it's surprising that the challenges faced with documentation for open source aren't that much behind the similar challenges at larger companies. The other biggest challenge: how to keep it up to date and who is responsible for that.

There was a debate at a recent conference about "open source versus closed source," citing the concern of people deleting or making undesired changes in open source projects. I think this is likely not a norm but it highlights a broader theme of "we don't necessarily know who is looking at the project, who may contribute, what their background is, and for how long they will be contributing."

To overcome this, having not only easy to understand documentation that includes a contribution guide and Readme with links to specific instructions on how to work with the repository, the documentation needs to be easy to navigate to and stay current.

These are challenges in volunteer organizations but I recently attended a Writing Day with a focus on improving documentation for attracting and retaining new contributors and building confidence in people without technical backgrounds in dealing with technical sides of documentation. It's quite scary going from closed source to open source where you can make drastic changes right out of the gate and that is a confidence thing but also hard to start volunteering somewhere and wanting to make major changes to their code.

Who writes this kind of documentation today?

Bekah: My background is in teaching college English, but you definitely don't have to have that! One of the maintainers of our docs speaks English as a second language. She understands the project, how to use it, the goals for our documentation, and the standards. For me, having her as a regular contributor has been one of the best parts of being a maintainer because she understands the project.

Ruqaiya: Technical content writer with the help of a team (technical and non-technical) to know more about the project and which end-user this project is for.

John: There is not a set person who writes the documentation, we don't have a technical writer and often falls back on the organizational teams to fill in when volunteer hours are not available or to seek assistance in opportunities like the Writing Day to have technical writing volunteers work on much needed documentation overhaul.

It is interesting - coming from non-open source and the world of Data Quality Management - to see there aren't necessarily much dictating or guiding what the documentation should look like or the needs are. There are templates and suggested practices - but from someone who may not have been involved with documentation before and now volunteers, this shouldn't limit them. But it's something that having documentation for the user story would benefit going from "zero" to "producing."

There are templates and the ability to prefill things like reporting an issue which also helps with the documentation, but that tends to rely on the project leads and above. There are also auto-docs, non Gen-AI specific, but in many ETL [Extract, Transform, and Load] tools there are documents that can be generated while compiling. These may not be the most-needed documentation, but processes like this helps bridge that gap.

What kinds of help would you like in your documentation?

Bekah: Updating out-of-date docs is always helpful. We've been some significant user interface changes recently, so I need to go through and do an audit of where we mention our "explore" page and the images we include for that. Not only does that include the docs, but the courses as well.

Also, we always love feedback. That could be on the product, the documentation, the organization of the docs, or general.

John: Finding ways to keep it up to date, reduce the amount of options for human error, and streamlining how to make changes quickly and make sure all sources state the same thing. It predates me, but we went through a name change for the project, and that was a bit of a hassle tracking all of those down.

I think the best documentation in the world is only going to assist if people know to look for it, that it exists, can navigate to it, and not be overwhelmed when trying to start out. Self-reliance to learn to read through documentation is not a widespread norm - but even with those docs there, it doesn't quite replace the ability to talk with someone to make sure you "aren't messing up."

I would like to explore YAML and Jinja templating more for our documentation, something that can be built and maintained through a simple yaml file. But I am not a technical writer so I don't always know all the best practices and tips.

I find that the documentation needs to be simple enough for a new person to understand but still be helpful for those with a background who are getting started, and that's a challenge as well.

What tools or technologies does someone need to know to contribute to your project?

Bekah: Our docs are maintained on GitHub and we use Docusaurus, which I've really enjoyed. We added a "Community Resources" section to the docs and added past blog posts that had only been on Dev.to. It's been a great way to boost our SEO and to have an alternate location to reference the materials we create.

Ruqaiya: Having GitHub experience like how to edit or modify content for upcoming contributors.

John: Code with the Carolinas is committed to finding an entry point for anyone with an interest in contributing to one of our projects. Right now the documentation is held exclusively in the Codeberg repository within the Readme, Contributing markdown files and the built in wiki. For our other projects, there is documentation specific to those projects held elsewhere, but we do not maintain those.

I've been exploring templates from the Good Docs Project but have not implemented those yet. We don't have source control on our wiki, which might not be a good thing, but we've been working on building out requirements such as PRs that need certain approval. But outside of here, I work mostly with docs that are served such as in dbt, docs hosted through a site , or with a yaml file that outlines essential information needed.

How can folks get started if they want to help?

Bekah: I think a great way to get involved is by taking a look at what we're doing and either giving feedback in our community discussions or by raising an issue if you find a bug or want to see an addition.

Ruqaiya: In our open source project, we have contribution guides and tasks written for new contributors. We also have a Slack channel and WA channel to help new members connect with us.

John: We're focused on community civic tech volunteering, so we're looking to connect with contributors in the states of North Carolina and South Carolina in the US. We host regular online Meetups to welcome new contributors to our organization and specific projects. Sometimes people find us from our Code with the Carolinas website and Codeberg repo and contribute as needed. We also have a Slack channel, which is joinable on either Meetup or through the main website.

The best way for someone to get involved with community civic tech volunteering is in their local community. In the US, they might reach out to the Alliance of Civic Technologists. The Civic Tech Field Guide is also a great global resource.

---

This was an excellent insight into technical writing opportunities in open source software. We'd like to thank John, Ruqaiya, and Bekah for sharing their experience and providing a great "on-ramp" for new contributors in open source software.