Open source documentation will improve collaboration

There’s always a thrill to see something that you’ve dreamed of coming to life. And for us, open source docs is the realization of that dream. In simple terms, open source docs mean that the documentation is freely available for anyone to modify. This is a part of the modern documentation movement, being able to make changes to keep pace with modern development cycles.

If you had questions or feedback in the 20th century, you had to write to a documentation or support team and maybe an errata page would get published but the issue would remain until the next publication of the manual. In recent years, you could comment directly on the page where the docs are published and the turnaround for a change would be less than a week. But in an open-source model, the text is available to you to suggest edits, right in line and they can be reviewed and responded to in a matter of minutes. This rapid response allows the content to become a living document instead of a snapshot in time.

Open source also means a community of users where you can contribute and interact. Although I know some of you love talking to us, and others are crazy good participants in CAB, sometimes you want day to day recognition for how much you contribute to the field of app monitoring. Making those contributions in open source code means that others can see your skills and collaborate with you on your ideas. Adding to the docs with your contributions makes you an expert.

Okay, I’m sold, how does it work?

How revolutionary can this be? Well for one thing everyone can edit from the same source base thanks to Github. This means contributions from developers, testers, product, and, wait for it, customers. Everyone contributes together, and the versions of these changes are tracked through Github, a tool developers already use. And you don’t have to have much Github knowledge if that’s not your thing, you can just edit from the website.

It’s entirely up to you, Neo, to choose the red or the blue pill, we accept both contributions to the docs.

Okay, the first line in the diagram is definitely a great choice for short-term single-page edits. If you are a GitHub newbie, come in, make a comment, and let us handle the rest through the PR. If you are suggesting edits of a couple of pages, a new article or use case, or something even larger, definitely clone the docs repo to make changes.

Now for the fun part, as you grow in contributions you can see how you stack up against other contributors. As you can see Kim (the golden retriever avatar) has definitely beat me this week in terms of contributions (as she does every week, she rocks) but one day I will triumph.

What tools did you pick and why?

So GitHub takes care of the authoring and editing of the source but what about the actual website? Well, there are many great players out there that can build and host static websites from markdown files in Git, including Gatsby, Jekyll, and Hugo. But for us, these tools took serious time to develop and customize. This means you spend less time working on the docs, and more time taking care of the code of the system.

For us, there was only one strong fit, Docusaurus. Written by Meta for their developer docs, it comes with a solid plugin library to handle everything redirects (cool right) to translations (coming soon!). This ease-of-use allows us to pick up features quickly such as tabbing, code sampling, and dark mode (my favorite mode) without having to devote significant programming time.

Come, join the fun!

We built this site because we believe we are definitely better with the input of others. As we grow our open source projects and community at Sumo Logic we want to encourage your engagement and participation. But you don’t have to take my word for it, come check out the docs site!