I went from confusion to clarity auditing Stripe's API Doc

Last week i promised to share what i got up to while auditing Stripe 's API, so here goes.

And pardon my pidgin, i no go lie for you, this past week was truly INSANE??

Jumped right into reviewing the API Doc with my little experience, which btw was an assignment by the Technical Writing Mentorship Program . My goal to tackle this assignment was to just understand the Doc (not the entire Doc tho, i was assigned about half of the document) well enough to offer feedback, but as I got into it, I realized it was quite deep.

Because have you gone through that Doc? Heh, God! Stripe’s API Doc is thorough, covering everything from basic API calls to complex integrations, but as a beginner, I found myself lost in the details one too many times. It was like reading a language I had just started learning, where each instruction held nuances that took time to process.

One of my key takeaways was the importance of clarity and consistency. I have to give it to the Engineering and Content team????. I thought Stripe had done a lot to organize their content, but I found some areas could still be simplified. For instance, I suggested adding clearer breakdowns of terms in almost all the assigned pages and sub-sections, as it would give new users a better foundation. Certain terms or API call sequences felt a bit too advanced for someone just starting out.

Another insight was around the examples provided. While Stripe included some examples, I felt they weren't related to typical scenarios. I recommended including more typical use cases that align with everyday needs and concerns, which would make it easier for users to understand how to apply the API effectively.

The parts that truly stressed me out were the Pagination and Balance pages. Understanding pagination was a lot, as the documentation explores how data is divided into pages but lacks a more beginner-friendly explanation. The Balance section was equally challenging, with its deep dive into handling accounts and balances. I had to reread these sections multiple times to grasp their nuances, but they left me with a stronger appreciation for the precision Stripe offers to users managing financial data. Once again, I no go lie for you, I felt the most mentally drained in these two sections because they had layers.

Ultimately, the biggest challenge was the vastness of the documentation. The number of endpoints and the level of detail Stripe offers are impressive, but it’s a lot to digest. As a beginner, I had to go over some sections repeatedly to fully grasp them. At some point, I was going to recommend a “Beginner’s guide” within the documentation, as it could be a gentle entry point before diving into the technical details.        

From just suggesting areas for improvement on the different pages, I started to understand better how API Documentation really goes beyond providing instructions that will help users navigate the API but guiding users at different levels through a structured journey. While this past week's challenge was a daring task, it solidified my foundation and also gave me a sense of accomplishment.

I am stoked to keep exploring this fascinating area of writing.

#stopingAtNothing??