Enhancing Developer Documentation: A Throwback to Write the Docs Conference 2024
Earlier this year, the BigCommerce Dev Docs team had the amazing opportunity of attending the Write the Docs Portland 2024 conference. Among all the networking, project showcasing, and speaking events, there was one theme that we enjoyed delving into – leveraging improvements and pipelines through Docs as Code.
We found that some of the conference ideas could really help our team create more interactive, resilient, and consistent docs:
Interactivity - Control content flow with graphic elements and code in content
Resilience - Keep docs fresh with testing pipelines
Consistency - Standardize docs with workflow automations
Read on to learn more about some of the ideas that might influence the overall direction of our Dev Center.
Inviting interactivity with dynamic elements
At the end of the day, we all know that no one gets paid to read. As Dennis Dawson expressed in his talk, , docs that are not too dense, but provide just enough to perform the job, may benefit the developer. Many developers want runnable sample code and complete API documentation to help them work efficiently. People want to take action, not read. So how can we create concise docs that kickstart the reader?
Conference talk - Graphic Relief: Beyond Flowcharts and Screenshots (Dennis Dawson)
It turns out that some docs more effectively invite the reader to interact with the product. Docs that don’t force the reader to switch contexts between doing and reading help the audience take action (credit to Dennis Dawson’s talk). Docs can show before tell, or vice versa. This might look like embedding video content before providing steps that spell out the action items. Readers can choose to watch the video or copy code snippets from the steps below as they learn.
At the conference, we saw some great ways to incorporate these visual elements into our docs. Writers have great flexibility over how we choose to display the elements when we use Code in Content. For a recap, check out Taylor Krusen’s talk, .
Reaching resilience with testing pipelines
Resilient docs are those that stand the test of time. They start off freshly published, stay accurate, and incorporate new info as breaking changes occur. The developer community really needs resilient docs, and our team constantly strives to have docs that never stale.
As the number of newly-released features skyrocket, we need creative ways to validate existing API calls in our docs and keep end-to-end guides up to date. A large portion of our docs includes REST API endpoints, their endpoint parameters, request and response examples, and response status codes for API calls to the server or storefront. Using these REST APIs often involves passing data from an API response to the request for another call, chaining a sequence of API calls.
We found that a testing pipeline approach might tailor well for our purposes. Manny Silva’s Docs as Tests is an open-source documentation testing framework that can help detect when docs run stale. This tool tests your content against APIs to help detect when response bodies, error codes, and more are outdated in REST API endpoints. You can also validate commands and scripts, and add it to a CI/CD pipeline to run tests in Github for a repository.
Crafting consistency with automations
As BigCommerce grows, the docs cover many domains across the company. There is an ever increasing number of internal and external developers who contribute content to the docs. In the midst of all the growth, having uniform style across our docs becomes a challenge.
Our team enjoyed exploring tools at the conference that could help craft consistent, standardized documentation. We came across platforms like Ekline that use AI-assisted edits in a publishing flow. This platform lets you integrate automations into existing workflow tools. You can monitor and analyze the consistency of your docs over time. Since we’ve been leaning heavily into Docs as Code, we’re always looking to incorporate new tooling into our existing processes.
Keep exploring
Excited about new ways to improve your documentation? Check out the for more.
If you have questions or feedback, please reach out to our DevRel team or join our Developer Community TODAY!