Improving BigCommerce Documentation: Understanding an Audience from the Ground Up

A brief memoir of my journey through a coding bootcamp to become a better technical communicator at BigCommerce

Studies show that as people gain deeper knowledge of a subject, they tend to internalize information so that the details don’t take up space in their working memory. When this happens, they’re able to perform complex tasks automatically. However, when explaining a subject to someone else, they might unintentionally gloss over the critical details that the audience needs -  a phenomenon known as “expert blind spot.” The details that they abstract away become hidden assumptions.

As I embarked on my journey in technical writing, I approached it with the mindset of a complete beginner. A large part of technical writing is understanding the technical content I was documenting and how end-users interact with products. But I also wanted to become aware of whatever hidden assumptions I might have later on and consciously pinpoint the details that would matter to the BigCommerce audience.

To start off, I enrolled in a developer bootcamp that provided hands-on learning and foundational knowledge of the tools and concepts I would be writing about. The bootcamp was a journey across vast seas, from learning about API integration to intricate client server architectures and REACT libraries. Each topic was a new island to explore, providing valuable foundations for understanding current technology stacks at BigCommerce - including the Stencil framework, innovative Catalyst systems, and cutting-edge headless architecture. As I delved into each new topic, I kept a diary to document my journey. I didn’t just need to know how something worked—I needed to remember what details once seemed important to me.

One practical example of this process was when I learned about using HTTP clients to make requests. While this may seem like a basic concept at its core, I took a fresh approach and treated it as a blank slate. From scratch, I tracked my footprints as a novice developer.

Keeping a journal helped me consciously pinpoint the details that were once important to my understanding of a subject

“An HTTP client lets you interact with web servers and APIs,” I scribbled. Seemed like a basic core concept. I fiddled around with a popular HTTP client, the Fetch API, and got some successful responses in the browser using example code snippets from a doc. I wondered if there were any gaps that would need further explanation.

For a different assignment, I tried to use the Fetch API to fetch data from a Node application. After fumbling around, I discovered that earlier versions of Node.js, by default, do not natively support the Fetch API. I made a note to myself that technical content should explicitly state the context and environment. It turns out that the Fetch API is built into browsers for client-side data fetching. There, the client is directly accessible without any external libraries. “It can also be used in server-side JavaScript environments like Node.js, in Node 18 and later, or with polyfills in earlier Node versions,” I jotted down. The audience needs to know this.

To continue exploring, I experimented with Axios, another popular HTTP client. I found patterns and subtle differences between Axios and the Fetch API. Comparing the two helped me figure out what information could be essential for users. When using Axios, I didn’t always need to parse JSON responses or stringify my request bodies before sending them. This was not the case with the Fetch API. I sat there for a solid minute pondering about what tasks were automatically handled for me. How is the tool simplifying work for the user? What common tasks do users not have to do? I noted whether there were default values for parameters that users would usually expect to input themselves.

The details that matter to an audience may change depending on the context of your tool. But in each case, you can treat the tool you’ve built as a blank slate and bring fresh eyes to the table to discover what you need to mention. When I embarked on my journey through the bootcamp, I became more attuned to how to make developer content accessible to those new to the BigCommerce community. 

At BigCommerce, we have documentation for our Catalyst Client. Let us know what you think! If you are interested in contributing, check out our Catalyst Discussions page on Github. 

You can also contribute to other BigCommerce developer documentation. To get started, see the Contributing Guidelines.