Open Source Adventures, Day 0

August 01, 2016

Today is August 1st. Now that I have been back in Bristol for a little while, it's time to knuckle down on a project that I've been thinking about in some form or another for the last few months.

I don't have many details yet because the ideas are still all in my head. However, I have a pretty good idea of the problem that I want to solve, so here's the summary:

As a software engineer working on a team, you want to write documentation to accompany your code. If your project involves multiple moving parts (for example a microservice architecture), it can be hard to keep documentation consistent and accessible across the different repositories that comprise the overall application. On one hand, you want to write your documentation alongside your code so that it stays up to date with changes to APIs. On the other hand, you don't want to have to trawl through 50 services' GitHub repositories to find the documentation on the one endpoint you care about.

I want to build a tool that allows developers to write documentation alongside code, but read documentation in a single, presentable, easily accessible way. In other words, a documentation tool that allows distributed writing and centralised reading.

Open source is amazing, and I have built my career on the shoulders of great developers who make the open source packages I use every day. For this reason, among others, I want to build this project in the open. If teams find it useful, and want to self-host the tool, I will be delighted. If I can provide a paid service for those people who don't want to run it themselves, in the style of Sentry or Nginx, all the better.

I want to make sure that I stay motivated and hold myself accountable while I'm working on this project, hence the announcement. I intend to post regular updates on my progress for anyone who is interested, and to make sure that I work consistently towards a goal.

If you're interested in more details, please let me know in the comments or via email. As soon as I have something tangible to show, I'll add links to a GitHub repository for anyone who wants to contribute!