Lukas Rosenstock's Blog

Lukas Rosenstock's Blog

Last night, the API the Docs community started their second season of regular virtual events. We had Milecia McGregor and Louis Debatte-Monroy in the speaker lineup for the first meetup.

Milecia talked about why technical documentation for APIs and developer products matters. She emphasized that code snippets in documents are of utmost importance because many developers are primarily looking for these. They don’t want to read all prose in detail and copy and paste examples instead. Hence, you lose some of your developers if the snippets don’t work, and if they have lousy quality, it reflects on your overall product. Milecia had an interesting suggestion to assure the quality of your code snippets. First, you separate them from your docs. If you’re using docs-as-code, don’t use inline code blocks but add references instead. She showed an example in Gatsy, which supports including the samples. Once you separate them into individual code files, you can write unit tests and run them as part of your CI pipeline.

Louis talked about audience segmentation for developer portals, emphasizing that “developers” is too broad of a term to describe your audience accurately. He suggested creating various personas, which can industry-specific. Create a one-pager defining each persona, even including information that doesn’t seem immediately relevant, to make them good fictional characters. You can brainstorm with your team in creating the personas and, once done, distribute them internally and use them whenever you create content. Louis showed a practical example, including one developer persona that reflected the exact copy-paster-type that Milecia described in her talk.

Both speakers, but Milecia in particular, made the point that I also make a lot, that developer content, and especially technical developer content with code appropriate for your audience, is vital to run a successful API program developer portal. It’s an excellent opportunity to remind you that I also offer consulting, development, and technical writing services to assist companies with this kind of content. Please contact me to learn more.

Also, if you’re interested in future API the Docs events, you can join them for free, thanks to the sponsors, but you have to sign up here.