Where Docs-as-Code Goes Next

Docs-as-code is the philosophy that your technical documentation should be produced and managed using the same tools and process as your code. This includes writing in your local dev environment, using Git for version control, and deploying through the same workflow.

There’s a number of benefits:

• All in one place: This makes it harder to skip the documentation, if the creation of the docs happens the same place the code does.
• Shared deploys: You can set it up so that your docs can go out the same time the feature does, so your launch is coordinated.
• Automation: Not all docs are written by humans… sometimes the best documentation is automated from your code!

You also get to take advantage of the rich ecosystem built around code: version control, automated tests, linting, pull requests and more.

Limitations

When I started ReadMe 10 years ago, ironically the most beloved value prop was that the docs weren’t locked up in Git. Back then, most documentation was tangled together with the presentation layer (the HTML and CSS for the docs site), and even a small typo fix required a herculean effort to deploy. Documentation sat stale, waiting for a developer who knew how to get it published.

Since then, a lot has changed. Developer tools have gotten better. Everyone’s gotten more technical. And the content and presentation layer are now separate, meaning the content is more accessible.

Our editor is still a solid way to write and manage your docs. The WYSIWYG editor is easy to use, but also gives you room to customize and build interactive docs. If you want to work in a visual way while still taking advantage of all the bells and whistles ReadMe provides, there’s a lot of great reasons to fire up the web editor.

Best of Both Worlds

We built ReadMe in a way where your team doesn’t have to choose where you write – everyone can write where they feel most comfortable. For people who prefer to write in their local dev environment, they can check the docs out via bi-directional sync and edit there. Or, for people who prefer a more rich, visual experience, our editor is always an option. You don’t need Git to use ReadMe, but now it’s there if your teams want it.

The best part is different people can seamlessly work together in different places. Git is the source of truth, and our editor is just a client on top of it. All our tooling (and all GitHub’s tooling) can be used, so you can write wherever and whenever inspiration strikes!

Why Now

We’ve rebuilt ReadMe on top of Git so your team can work with docs the same way you work with code. With features like branching, it’s easier to collaborate, review changes, and ship docs alongside your product. Whether you’re writing in your IDE or in ReadMe’s editor, everything stays in sync so that your docs will keep up with your code.