In fashionable software program improvement, agility isn’t a matter of velocity — it’s about being adaptable, open, and constant. Whereas a lot of the eye in Agile improvement is concentrated round iterations, sprints, and steady supply, documentation usually falls behind.
However what if the documentation may sustain with the code? That’s precisely what Documentation as Code is about.
At its coronary heart, this method treats documentation like software program code: it’s versioned, re-inspected, examined, and deployed utilizing the identical instruments and workflows.
This idea is in actual alignment with the “Single Supply of Fact” philosophy that makes an attempt to convey and solidify info collectively in a undertaking so it doesn’t create confusion, redundancy, and miscommunication.
Let’s dive into what Documentation as Code (Docs as Code) is and the way it allows this philosophy in Agile settings.
What Is Documentation as Code?
Documentation as Code refers back to the apply of writing and supporting documentation utilizing the identical processes and instruments which are used for writing code.
As a substitute of storing technical content material in exterior programs reminiscent of Phrase paperwork or wikis, Docs as Code shops all the things in a model management system, usually Git.
Because of this documentation:
- Lives in the identical repositories because the supply code.
- Is written in light-weight markup languages reminiscent of Markdown or AsciiDoc.
- Follows the identical branching, pull request, and code overview workflows.
- Is built-in into the CI/CD pipeline, the place documentation could be routinely linted, examined, and deployed.
The important thing rules of the Documentation as Code philosophy collaborate with each other to maintain documentation exact, up-to-date, and straightforward to control.
To start with, by utilizing model management, each change to the documentation is tracked and could be rolled again if wanted, identical to with code.
Automation, in flip, helps simplify the method — builds, previews, and error checks occur independently, which implies much less work concerned and faster supply.
Additional, as a result of the identical device units are used when creating customized software program, collaboration is manner simpler. Builders, product managers, and technical writers may even contribute in keeping with established workflows.
The One Supply of Fact Philosophy
One Supply of Fact implies having info in a one single location, which everyone on the crew can seek advice from.
It’s easy in Agile improvement to have the documentation get unruly — there could be a few of it on wikis, some on shared drives, and a few buried in previous electronic mail threads.
With Documentation as Code, in flip, the Single Supply of Fact turns into the codebase itself. The documentation exists alongside the code, in the identical model management repository, and makes use of the identical workflow.
Put merely, any alteration to the code could be adopted by the matching documentation replace and everybody routinely is aware of about it.
By linking code and documentation collectively, groups keep away from duplication, scale back errors, and facilitate communication. This fashion, it’s a lot simpler to belief documentation — as a result of it will get up to date identical to the code, and by the identical folks.
Advantages of Documentation as Code in Agile Software program Improvement
General, Documentation as Code possesses some compelling advantages in Agile improvement, serving to groups work quicker, wiser, and with fewer misunderstandings.
First, it retains documentation updated. As a result of it’s being saved and stored with the code, any modifications could be carried out and reviewed directly. No ready for an individual to revise a separate doc or wiki down the road.
Second, it improves teamwork. All of the contributors, from builders and testers to writers and product managers, can contribute to the documentation utilizing the identical instruments they use to code.
Third, it impacts the code’s high quality. Writing and validating technical documentation concurrently with code forces builders to pay extra consideration to how their code behaves, which tends to result in a greater design with fewer bugs.
Fourth, builders can add automated checks and assessments to the CI/CD pipeline. They will routinely discover damaged hyperlinks, misspellings, or out of date references within the docs, the identical manner they’ll discover code.
Lastly, quite a few affluent corporations are already working towards this method. GitLab and Kubernetes initiatives have indicated that placing documentation into the event course of leads to extra steady, useful, and easier-to-use documentation.
The best way to Implement Documentation as Code
Getting Documentation as Code stay isn’t that tough, however it’ll take you to change the way in which your crew operates. One of the best recommendation right here is to start out small and regularly transfer towards making Docs as Code part of your course of.
1. Begin Small
To start with, select a small undertaking or a selected module to doc utilizing Docs as Code. This step permits your crew to get acquainted with the method with out feeling overwhelmed.
Then write documentation for one or two options or parts and retailer it in the identical Git repository as your code. This fashion, you’ll get a really feel for the way documentation could be handled like code.
2. Use the Proper Instruments
Subsequent, double-check you’ve the best instruments at hand. For model management, you’ll need to use a system like Git (with GitHub, GitLab, or Bitbucket).
For writing the documentation itself, you need to use easy markup languages, reminiscent of Markdown, AsciiDoc, or reStructuredText.
Additional, take into account making use of static website mills like MkDocs, Docusaurus, or Hugo to show your Markdown information into knowledgeable, user-oriented documentation web site.
Lastly, combine your documentation into your CI/CD pipeline (e.g., GitHub Actions, GitLab CI, or CircleCI) so as to auto-format checks, spelling checks, and deployment.
3. Incorporate Documentation into Your Workflow
When you’ve the instruments arrange, it’s time to merge documentation into your improvement workflow. Put merely, it means inserting documentation adjustments in the identical pipeline as code adjustments.
If a developer creates code, they have to additionally replace or add the respective documentation in the identical commit. To maintain all of the components organized, it’s essential to create pull requests for documentation adjustments and overview them identical to you’ll overview code adjustments.
4. Educate Your Group
Apart from, it’s vital to teach your crew on how Docs as Code works. This implies explaining the instruments you’ll use, the workflows, and the advantages of getting documentation in model management.
Have interaction builders, product managers, and technical writers to play lively roles in including to documentation. Collective accountability will make documentation a crew effort, not the only real accountability of 1 particular person.
5. Keep away from Frequent Pitfalls
On the identical time, watch out to not fall into widespread traps when going Docs as Code. One mistake to keep away from is over-engineering the documentation course of on the onset. As a substitute, simplify issues first after which add more and more extra advanced instruments or processes.
One other mistake is forgetting documentation after the preliminary setup is full. As a way to maintain your docs up-to-date, embody them within the CI/CD pipeline and encourage common overview. A quick reminder: for those who maintain documentation a low precedence, it’ll simply fall behind.
6. Undertake Steady Enchancment
Lastly, keep in mind that Docs as Code is a steady course of. The extra your crew will get used to the workflow, the extra it is possible for you to to streamline and refine it much more.
You possibly can, for example, add even higher automation, enhance the type, and even add person suggestions to additional improve the documentation. What is crucial is to deal with it as a long-term funding that pays off within the type of higher collaboration and a greater improvement course of.
Challenges and Concerns of Creating Documentation in Software program Improvement
One of many greatest challenges is to maintain the documentation updated when the code is being edited. To resolve this, there’s a must replace the documentation and likewise the code.
One other downside is duplication. Programmers prefer to remark within the code how issues are completed, and sometimes this repeats the documentation.
Whereas code feedback are vital, they have to concentrate on technical particulars within the code, and the documentation ought to present clear, high-level info for customers.
Adopting Docs as Code additionally requires remodeling how the crew works, which could be difficult for people used to conventional documentation. A few of the crew members may resist at first, however with time, once they see the advantages, it turns into painless.
Though automation helps, it will probably’t do all the things. Instruments can seek for small errors, however they’ll’t inform if the documentation is unambiguous or useful. That takes human involvement. Reviewing the documentation regularly ensures that it’s worthwhile and correct.
Lastly, as your undertaking progresses, the system documentation can turn out to be outdated or disconnected from the place the product is. To forestall this, it’s vital to have evaluations and updates regularly.
Having an individual who has the accountability of keeping track of particular areas of the documentation may also maintain all the things correct and true to life.
| Problem |
Answer |
| Maintaining Documentation As much as Date |
Replace code and documentation collectively. |
| Duplication of Info |
Hold code feedback technical; documentation ought to concentrate on high-level information. |
| Adopting Docs as Code |
Regularly transition, displaying advantages over time. |
| Automation Limitations |
Common human evaluations to make sure readability and accuracy. |
| Outdated Documentation |
Common evaluations and updates to align with the newest product model. |
| Lack of Possession |
Assign crew members to supervise particular areas of documentation. |
Actual-World Use Circumstances of Leveraging Software program Documentation
To get an thought of how Documentation as Code operates in precise environments, let’s analyze some use instances of corporations and initiatives which have efficiently enforced this technique.
The instances beneath research illustrate how Docs as Code aids in enhancing collaboration, sustaining related documentation, and making the event course of extra ample.
1. GitLab: A Chief in Docs as Code
GitLab, a well-known DevOps and CI/CD device, is a superb instance of an organization that has welcomed Documentation as Code.
Its docs are saved in the identical Git repository because the code, and your complete crew works collectively to take care of it as much as the minute.
The corporate makes use of GitLab’s personal CI/CD pipeline to routinely produce and deploy the documentation each time a change is pushed to the codebase.
Because of such an association, all undertaking members can simply entry and leverage the documentation. And since it’s a part of the event course of, GitLab sidesteps the basic downside of documentation rising outdated or forgotten.
It additionally unites your complete crew—builders, technical writers, and everybody else can contribute to the documentation in the identical manner they contribute to the code.
2. Kubernetes: Open Supply Success
Kubernetes is yet one more nice instance of how Documentation as Code is practiced.
All person documentation and API references for Kubernetes are stored in the identical Git repository as their code. This means that each time the software program is being altered, it’s easy to replace the documentation too.
In addition they make use of automation to verify for issues like hyperlink breaks or out of date code examples.
General, because of this course of, numerous contributors repeatedly refine the code and documentation at common intervals, guaranteeing that each piece of labor is present and reliable.
3. Stripe: Maintaining Documentation in Sync with Code
Stripe, a longtime cost firm, additionally makes use of Documentation as Code to maintain its API documentation updated.
As their crew adjusts their API, they modify their documentation together with the code throughout the identical Git repository. This fashion, all edits are immediately mirrored within the official docs.
By together with documentation in the identical course of as coding, Stripe avoids the inconvenience of sustaining separate documentation and supplies customers with the newest and finest info always.
The Position of Technical Writers in Docs as Code
Within the strategy of Docs as Code, technical writers have a particularly vital place. Whereas the builders write down the technical info, technical writers double-check that such info isn’t tough to learn, structured adequately, and straightforward to know for everybody.
Technical writers rework difficult technical language into components anybody can perceive, and that is particularly important in Agile initiatives the place each software program and documentation get developed hand-in-hand.
Technical writers additionally work with builders, utilizing the identical Git repository in order that the documentation is at all times updated with the newest code.
Their data makes the documentation correct, well-organized, and useful. They overview updates, accumulate recommendations, and use automation instruments to catch small errors.
Typically, technical writers fill the hole between the technical facet of improvement and the wants of customers, making the entire documentation course of a hit.
FAQ
What’s “Documentation as Code”?
Documentation as Code is a apply of writing and conserving documentation in the identical manner builders write and maintain code — via automation, Git, and model management. It retains the documentation up-to-date, reviewed, and versioned identical to the software program itself.
Do builders write all of the documentation in Docs as Code?
Not essentially. Whereas builders will contribute, technical writers are nonetheless obligatory. They make the data properly organized, readable, and clear to customers, even when it’s written in a code repository.
Why is it essential to maintain documentation in the identical Git repository as code?
Maintaining code and documentation separate signifies that each of them could be up to date on the identical time. It avoids stale info being utilized by groups and ensures customers get the newest and most correct documentation on a regular basis.
