By Fabrizio Ferri Benedetti, Robin Pille, and Christopher Gales
As part of our long-term documentation strategy, now anyone, from Splunkers to Splunk users, can improve the Splunk Observability Cloud documentation by adding examples, documenting new settings, or fixing issues. By opening the Observability docs for community contribution, we’ve made it easier to ensure we’re providing the highest quality, most up-to-date content for you to use every day. All you have to do is select the Edit this page link on any page of the Observability Cloud documentation.
The Splunk documentation team believes that the product is docs, and that great docs are key to the success of great software and the success of its users. Together with the existing Feedback feature, the Edit this page link is the simplest and most direct way to ensure that we’re providing the highest quality, most up-to-date product documentation.
The customers, partners, and Splunkers who comprise our community (that’s you!) are passionate about sharing their knowledge and experience to help everyone successfully implement and use Splunk software. You have proven that you’re invested in our documentation and want to work with us to make it great. That's why we're giving you a new way to contribute directly.
Why we’re opening the docs for community contributions
Open source contributions and docs-as-code principles are at the core of how the Observability docs team works. Prior to now, the docs were in an internal repository that let any Splunk employee review and edit the docs. Making the jump to publicly available source is a natural progression in our journey to empower users, and the first step in making more Splunk documentation content available for community contribution.
Opening the docs to community contributions also improves our efficiency and responsiveness. Every month we get dozens of feedback tickets from Splunkers and customers. Many of them are quick corrections that our feedback submitters could solve immediately if they had direct access to the source files. By giving you, the user, the power to edit the docs, we’re increasing the speed of improving the docs and creating a more effective feedback loop.
All things small and beautiful...and editable
What are the types of things you can contribute to the Splunk Observability Cloud documentation? There are many! Docs require constant care and we always strive to improve the relevance and usefulness of our content. In only a few minutes of your time, you can:
- Add new code snippets and examples for our instrumentation and agents.
- Update broken links that point to Splunk documentation or external sites.
- Correct incorrect information, like a wrong default value or command.
- Update outdated screenshots and animations to reflect the current UI.
- Fix formatting glitches, wrong capitalization, duplicated words, and more.
You can also submit deeper changes, such as conceptual explanations, diagrams, and even entire new topics that can benefit all users. If you’re entering the technical writing profession, adding docs to our repository is a fantastic way of adding new samples to your documentation portfolio. There’s a free trial of Splunk Observability Cloud you can use to get started.
If you’re unsure about a change or have a different question about the docs, you can still always use the Feedback button at the bottom of every page to let us know of a documentation issue, and we’ll do our best to respond as soon as possible, just as we’ve always done. Now, though, you have an alternative: you can submit the changes yourself.
How to get started with docs contributions
On every page of the Observability Cloud docs site you can find an Edit this page link. Select the link to load the source of the document in a GitHub preview. The only prerequisite to edit the docs is having a free GitHub user account.
After you’re done with your edits, GitHub prompts you to open a pull request and fill out the description of the changes using a template. Within 72 hours, we’ll make sure to review your pull request and publish it on the site if everything looks good. Should we reject it, we will tell you the reason and continue the discussion.
You can learn more about how to build and test the docs locally, as well as our review criteria, in the CONTRIBUTING.md file of our repository. The file contains basic reStructuredText guidance and links to the Splunk Style Guide, which provides the guidance we use to create consistent, high-quality docs.
Are you ready to help us bring our docs to the next level?
$ git add all
$ git commit -m "Let's write the o11y docs"
$ git push
