We can all agree that repeating the same information over and over wastes time and that writing comprehensive and accessible documentation is essential. But have you thought about how you’re creating that documentation? Are you still dusting off printed instructions or digging up ancient word documents? Is there a more modern approach?
In my opinion: "Boilerplates" are beautiful. They make using a new framework, language, or platform possible without starting from scratch, and can vastly simplify starting a new project. To simplify my documentation creation process, I've made a Kontent + Docusaurus boilerplate that will handle styling, navigation, and structure, while also allowing me to maintain my content using a headless CMS.
In this article, I’ll talk about the benefits of using Kentico Kontent, Facebook’s Docusaurus, and my Kontent + Docusaurus boilerplate to create scalable, attractive, easy-to-manage documentation.
Why my documentation went “the way of the dinosaurs”
I wear a lot of hats in my organization: I’m a manager, support engineer, content creator, internal trainer, to name a few. Shifting attention between varying tasks and functions is a common occurrence and can be pretty overwhelming. To save time (and my sanity), documenting my processes and responsibilities helps me stay organized and allows me to delegate tasks to my team more effectively. But until recently, I didn’t have a great way to create this resource. I’ve used our crowded company wiki, Word documents, PowerPoint presentations, and a lot of information is given verbally from memory. Something had to change as this approach locked me into a perpetual loop of updating static presentations and documents with no hope of delegation.
How does it help you?
Maybe you’re not managing a team or on-boarding anyone, but I’m confident at some point you’ve had to walk a teammate or multiple colleagues through a process a few times. Let’s be fair: your colleagues don’t want to take valuable time away from you. They just need answers, and those answers happen to live in your head, are hiding in your notes, or are just not documented in an accessible location.
Furthermore, updating and maintaining documentation or guides doesn’t have to (and normally shouldn’t) rely upon developers, specialized, or senior team members. You should be able to write the original copy, hand-off the maintenance to a colleague or team, and move on to other tasks that are burning for your attention.
The boilerplate: Our cloning DNA
Creating a new piece of documentation shouldn’t be an ordeal; you don’t need another project vying for your time. Using a template as a starting point is a good way to make sure starting the documentation isn’t a major line item blocking out your calendar. So clone this repository and save time—no prehistoric mosquitoes required (you knew a Jurassic Park reference was coming).
This boilerplate comes with:
- A navigation sidebar with collapsible sub-sections
- Attractive pre-made styles, including light & dark mode
- A minimal amount of content to act as a “starting point”
- Quick and easy setup instructions in the Boilerplate’s documentation or GitHub README
Kontent + Docusaurus boilerplate pictured above.
The headless CMS: Advancing our reptile brains
When documentation is required, jumping into a simple word processor is second-nature to a lot of us. It’s comfortable, it’s quick, it’s familiar. This doesn’t mean it is the best approach for the job, though, and I argue that breaking this habit is key for making scalable and accessible documentation. Using a headless CMS addresses scalability head-on and future-proofs your documentation.
I work in Kentico Kontent all the time, so it is a go-to comfort pick for me when choosing a CMS, but those who aren’t fluent in Kontent will still reap major benefits from using it:
- It’s a Software-as-a-Service platform, meaning no managing upgrades, hosting, or security patches.
- Kontent’s search bar, filters, and “Home” allows you to quickly locate content.
- Inserting code snippets into the Rich Text Editor using a WYSIWYG editor is easy.
- Reusable content and content links mean no more copy-pasting swaths of documentation between sections.
- Its features, API, and SDKs are well documented.
Sample content item in Kentico Kontent pictured above.
These are just a few of the benefits when using Kentico Kontent, but if you need more proof, the official Kontent documentation uses Kontent, and there is a two-part article series that talks about why.
Docusaurus: More Barney than an apex predator
In addition to the list of benefits from Docusaurus’ website, the plugins and presets provided by the Docusaurus team make getting up and running fast. Its creators’ focus on documentation sites, along with 20,000 GitHub stars and being backed by Facebook, is what really drew me to using Docusaurus as the front-end application for my documentation. It’s also a nice fit because:
- It’s a static site generator making it fast and secure.
- It can be deployed and hosted virtually anywhere for free.
- The Docusaurus team wrote easy-to-read documentation about everything from Installation *to *Lifecycle APIs.
This React and MDX markdown powered project has T-Rex-level power in its extensibility and out-of-the-box functionality, but the features and configuration are intuitive, so its learning curve isn’t intimidating. For example, in just three terminal commands you can have their classic preset site running. Docusaurus is definitely a friendly dinosaur.
So...is it actually fantastic?
For me personally, I’m a lot happier to point a colleague to up-to-date stylized on-boarding resources than having to muddle together PowerPoint presentations, but this depends on your use case. If you just need a few quick, static paragraphs to document something, Kontent + Docusaurus might be overkill. But, if you have living documentation that needs frequent updates, reusable content, and structured navigation, it could be a better choice than passing around Word documents or jamming information into overflowing wikis.
Additionally, since the content is available over an API in a headless CMS, this documentation can evolve with the times; Create a voice-app that pulls the documentation from Kontent, integrate personalization to better serve the visitor, add analytics or commenting with machine learning to gauge the helpfulness of a page. The possibilities and complexity can scale with the project needs. I’d say that’s pretty fantastic!
Kentico Kontent architecture possibilities pictured above.
Can I see this evolution in action?
Absolutely! The documentation explaining how to set up the Kontent + Docusaurus Boilerplate was written using Kontent and Docusaurus. You can also set up your own project using the instructions in the Kontent + Docusaurus Boilerplate GitHub repository.
Don’t wait for a meteorite
In this article, we highlighted the benefits of replacing old documentation with Kontent and Docusaurus and how a boilerplate can streamline your documentation creation. So don’t wait for a cataclysmic event, blow up your ancient documentation habits, and give Kontent and Docusaurus a try!
Top comments (0)