CircleCI docs are built by you: celebrating our open source contributors

At CircleCI, we have noticed the positive impact of developing documentation as an open source project because every improvement, large or small, helps thousands of readers that same day. CircleCI documentation is open source because working in the open results in better documentation and enables a greater variety of people to influence and change documentation efficiently.

Thanks to our contributors

As the manager of engineering documentation at CircleCI, I want to recognize and thank all of our amazing contributors to the circleci-docs repository on GitHub. In the last month, thirty-three authors have merged improvements to our public docs repo! Special shout-outs go to community members stmcallister, smasuda, mikegee, skion, and gfoidl for their pull requests. CircleCI 2.0 docs unique visits/month

Whether you’re a new or seasoned developer, we appreciate your contributions to docs. Contributing is a great way to add some open source experience to your resume (useful for developers and technical writers) and an excellent way to participate in CircleCI by sharing your expertise and knowledge. We have grown to nearly 60,000 unique visitors per month on the 2.0 documentation collection, so even a small contribution or typo-fix helps a large audience of readers develop better code with CircleCI. You’ll also be in good company! Our internal contributions come from every corner of CircleCI including Sales, Support, Engineering, Marketing, and Product Management.

Notable contributions

Translating docs into Japanese

In December 2018 we received our first complete translation from a community member, Naturalclar, who localized the instructions for using CircleCI status badges into Japanese. We warmly welcome docs localizers to our community and appreciate the effort to provide excellent translations for our Japanese developers. We already have over 1,700 visitors per month to the Japanese documentation collection.

Japanese docs: unique visits/month

Orbs publishing process updates

In March, danielcompton contributed doc updates and feedback to clarify the CircleCI docs for orb publishing. Sharing his perspective and suggesting a new way to describe the process made this doc much clearer, and his contribution will help every reader that follows those instructions more easily in the future.

Directory fixes and typos

In February jodastephen made a pull request to update the setup for Maven/Gradle test metadata and called out some information in the document for other frameworks that helped us get the document updated. Later that month, friederbluemle updated 49 docs files in a PR to improve consistency of the use of trademarked terms and variables.

Language guide improvements

In April, stmcallister updated the links in the Go Language Guide to make the sample project repo easier to find in the document and smasuda added an option to prevent running out of memory when running a command in the Haskell Language Guide.

Filing detailed issues

In the last quarter, we also had several detailed issues filed that help us know what needs to be improved in our documentation. This is a great way to participate if you don’t want to make a pull request! Just go to the New Issues page, pick the type of docs issue you want to file, and click the Get Started button to submit the information to the CircleCI docs team.

doc-issue.png

For example, y-nk filed an issue about missing information for uninstalling the CLI in the Using the CircleCI CLI document and Aghassi asked a question that helped us clarify information about how to manage repo org changes and CircleCI contexts.

I want to share our gratitude to all of these folks and many more who help us to continuously make CircleCI docs great!

So, would you like to contribute to CircleCI Docs? Here is some helpful information to get you started:

Contributing to CircleCI docs

All are welcome to our community! CircleCI merges PRs from 20 to 30 contributors per month to the docs repo, 15% are technical writers on the CircleCI docs team, 60% are engineers or product managers at CircleCI, and 25% are open source contributors. We will always prioritize merging your additions to our docs to help every reader who uses those docs after you! If we can’t merge it straightaway we will get a technical reviewer to check and amend your suggested changes so we can merge your PR.

How to participate

You are welcome to participate in CircleCI docs wherever you feel you have expertise or interest, if you want to learn something by writing new documentation, or if you want to share your knowledge by improving existing instructions. We strive to create world-class CI/CD documentation, and we do this through the contributions of the entire CircleCI developer community. We also want to be a place where our developers have influence, and can help create this part of the product, support all CircleCI users, and help them to discover how to get the most out of CircleCI.

With that in mind, the following section outlines some areas where we would love to work with you on documentation if you need inspiration!

Contributing to quality

Everyone can contribute to improving overall quality of CircleCI documentation in the following ways:

• Add comments to YAML examples that explain the keys and provide URLs to related documentation.
• Add links from every doc to the Glossary where we mention terms that are unique to CircleCI.
• Add new terms and definitions to the Glossary to make it more complete.
• Add links between related documents in the inline text. For example, anywhere we mention the word ‘cache’ or ‘caching’ we should link that word to the Caching document.

Contributing to examples

Anyone who is using CircleCI on a public project can contribute examples to CircleCI documentation:

• If you have an open source project that uses CircleCI, consider adding it to our listing of projects, so other developers can learn from your config.
• Consider adding commented examples of your config snippets to our existing documentation on a particular subject.
• We would love contributions of your example Workflows and Orbs in your config since these are relatively new features, but have so many permutations that more examples would help users to create their own customizations.

Contributing to API docs

If you have a use case for your application that calls the CircleCI API, you can document the use case for your application with details of the example call.

Contribute to ops best practices

If you are managing your own installation of CircleCI, you can contribute feedback on the new Installation and Operations documentation for v2.16 by opening an issue with your suggestions, requests, and feedback.

Some more basics about contributing to the docs:

• We author in Markdown and use Jekyll to publish the static site. See the circleci-docs.circleci/config.yml file on GitHub for our config.
• We recently added scripts to build the Slate API documentation, so you can contribute a PR to the markdown source files, and on merge, it will generate and publish the Slate files.
• We have a simple contributing guide, style guide and templates to help you along the way!

Ready to make your mark? Explore the docs.