Adapt the “Docs Like Code” Approach to Supercharge Your Product Knowledge Base

Heard of docs like code? You probably have. In the last year, it experienced a surge in popularity, not least in the documentarian community itself.

SaaS businesses are waking up to the idea of treating docs like code, though this approach is not entirely new. 

It’s been the traditional way of docs and code in open source communities, where the documentation typically lives with the source code (when it exists at all!). This idea is slowly filtering into the business world – and can work particularly well for SaaS companies.

There are some software engineering practices that can really help you with your docs.

• How you treat source code
• Version control
• Continuous delivery model
• Check-in policies
• Review process (testing)
• Taking it to production (public)

Treating docs like code means keeping your documentation in the same system (usually something like GitHub) as your source code, and employing the same development processes.

It means collaborating on documentation across the whole team and not having technical writing and engineering in silos.

Software development and technical writing use the same processes and development methodologies – treating docs like source code.

Background to docs like code

In the software industry, there is a lot of focus on code – and why not! It’s the core part of our products. Good, clean, well-commented, working code is an absolutely essential deliverable.

At the same time, documentation is crucially important. The problem is ending up in this either-or trap, where we feel like we have to choose between documentation or code. The reality is that documentation should be seen as equal but different to code, and this is the foundation of the docs like code approach.

In the agile methodologies, docs are often treated as anathema to code – viewed as slowing down production, and an unnecessary ballast in your rocket-propelled journey to launch.

Documentation should be necessary and relevant to software teams, rather than a box-ticking exercise as in traditional waterfall approaches to development. The best way to produce the right documentation for your team might be docs like code.

The Knowledge Base Software that scales with your Product

Request a demo

Why docs like code is needed?

The approach has been popularized even more by Ann Gentle after she published her well-known book Docs Like Code, and her website, which is named the same. The tagline of her book is: Write. Review. Test. Merge. Build. Deploy. Repeat. This reflects how docs production can come into line with the process of software development.

She tackles the idea of the artificial knowledge hierarchy in high tech – that code is innately superior to other forms of knowledge or skills. This results in dismissive attitudes towards deliverables that are not code, also viewed as ‘a waste of time’.

This may have made more sense as the legacy of technical writing caught up with modern software development practices.

In the past, technical writing teams managed their documentation using large, unwieldy publishing systems with expensive licenses and had limited user experience. Collating documentation after code developed did indeed take a lot of time.

There is understandably a lot of appetite for docs like code – especially as budget goes down and the pressure is on to step up production.

Advantages

There are many advantages to using a docs like code approach. Here are some of the top reasons to make the transition:

• It helps to keep the docs in line with the source code, and end users see the most up-to-date version for the docs
• It means you can work closely with the subject matter experts who will be best placed to provide initial inspiration for the documentation.
• You can use version control to help manage the editing and collaboration process, making it easier to revert to earlier versions
• Docs are given more importance as you can disable merging until documentation is delivered

Disadvantages

Docs like code will not be suitable for everyone. It’s important to bear in mind the limits of this approach before you go making any hasty decisions.

• It can be exclusionary to non-technically-oriented team members and tools have a steep learning curve. New technical writers may need training to get them up-to-speed, increasing the cost of getting the team to maximum productivity.
• Docs are not entirely like code and you can run the risk of trying to force a square peg into a round hole if you try too hard.
• It may not be possible to give technical writers clearance to use the same tools and systems as engineers.
• Culture change is hard. You may meet some internal resistance if this is not how your team usually does things.

How to make it work?

Closely related to agile methodologies, docs like code is the up-and-coming way that modern development teams will collaborate to produce docs – and code.

To combat engineers viewing documentation as a waste of their time, put docs on the same level as code. Make it a requirement for your engineers to create the necessary documentation before merging their code.

If your developers are producing docs, stop this now. Developers need to do what they are paid to do: write code and develop software. You need to hire a professional technical writer to be responsible for your docs.

Embed your technical writer(s) with your developers for each software project right from the very beginning. Avoid that mad 48-hour scramble at the end of development to put docs together so your software can ship on time.

If your technical writers are having trouble getting used to the version control platform used by the development team, you can look into using a knowledge base software.

It will save you the trouble and resources of having to train your technical writers. And it will generally make it easier for them to do their job. However, this implies that developers and technical writers will have to coordinate with each other to match their pace.

This entire approach will have to come top-down from senior management, in order to enable the whole team to come on board.

Simple and intuitive knowledge base software for your business needs

Learn more

Final remarks

There is no single right way to deploy docs like code. It depends on each team and company how you will make it work.

Many teams are already using docs like code approach and it is set to become even more popular. Even the British government digital services department employs a docs like the code approach for technical documentation.

To do it successfully, you have to integrate your documentation with your existing engineering processes – while bearing in mind the need to update documentation regularly, and not necessarily in line with software development cycles.

Technical writers will need to correct that missing comma, and they need to correct it now.

Also Read: Ultimate Guide To Create an API Documentation with Examples

To get started with docs like code, ask yourself:

• Who is responsible for shipping the docs?
• What is the most essential documentation that we need?
• What documentation do we want to produce?
• How will our docs look like?
• When do we need it by?
• Who can contribute to the docs?
• How will we handle versioning?

Find the answers to these questions, and then launch your docs as code strategy.

Where to go from here?

Here is a comprehensive explanatory video related to this topic for you to investigate further:

• A complete video on Transforming your Documentation Process 

By now, you should have a clear understanding of what docs like code approach means and how it can be beneficial for your product.

Regardless of the development stage, you should be writing documentation at the same pace that you are writing code and adding new features.

Writing documentation does not require extensive training for your writers anymore. In fact, you can take advantage of knowledge management software to maintain your documentation up-to-date with your code and its different versions.

If you think that we might have missed something, or if you would like to share your thoughts on this, please let us know in the comments section below.

Document360 is documentation solution for SaaS teams. Take advantage of your free trial now.