Back to Blog

Improving documentation of open source software

Team working on open source documentation

Team working on open source documentation

Four years ago, we at Futurice started to sponsor the free-time open source activities of our employees through our Spice Program. At the beginning of 2019, we expanded it from open source to developing your professional skills while making social impact.

We have many people who are passionate about open source and contribute to the world on a regular basis. In January 2019 alone, our people reported over 1000 hours through the Spice Program. We also have many people who believe that good documentation in any project — open or closed source — can make a huge positive difference. Whether it’s onboarding new users application, library or API, or it’s on-boarding new team members or contributors without requiring someone to pass along tons of tacit knowledge.

Unfortunately, the state of documentation in software projects is not great. In his talk, Write the Readable README, Daniel D. Beck talks about his research of over 200 popular open source projects and the results that were not flattering. 17% of them didn’t even include the project name in written form, and 31% of them had no description of what the project is about.

spice-docs-thursday

A few weeks prior to the event, I came across a blog post about DocsThursday, a new initiative to promote documentation and open source, and decided to gather together the enthusiasts inside the company for a Thursday evening event. So instead of complaining about poor documentation, we decided to make a difference.

The evening consisted of pizza and drinks, smooth jazz in the background, and lots of good discussion and work on open source projects. We started with our very own James Stone giving a presentation on good documentation practices and tools that help you build those documentations.

docsthursday-james2

“What is more irritating than code examples that don't work when you copy them into your project? That's exactly how I feel when when using Preact. It's almost like React, but it's not. Same goes for preact-testing-library, which is almost like react-testing-library, but it's not. The examples don't work out of the box. This is why it's important to have a separate documentation page for preact-testing-library.”, says Olavi Haapala, who worked on improving the documentation of preact-testing-library.

One of the benefits of working together like this, even on different projects, is that you have people around you to get ideas and feedback from. The event was internally well received and we’re definitely going to continue these kind of themed open source events — maybe even opening them up to the public in the future.

Here at Futurice we value continuous improvement and we want our employees to be able to give back to the community while learning new skills. Through the Spice Program, you can work on open source projects – and that means any open source project, the company doesn’t mandate or claim IPR – to learn new skills while making a positive contribution. If you are passionate about open source and making a difference, we are looking for developers to join Futurice. Learn more about us at https://www.futurice.com/careers/.

Author

  • Portrait of Juha-Matti Santala
    Juha-Matti Santala
    Developer Advocate