API Documentation

In the last five years API documentation has changed radically. What was once considered a stodgy requirement is now critical for most companies. My experience in the finance industry has taught me one thing: technical writing isn’t what it once was.

The Problem

For 20+ years technical writers were ‘those people’ who wrote content for a living in MS Word. Often called fickle and introverts, their existence was essential for long-form printed documents and manuals. Not anymore.

The advancements of API functionalities has propelled the software development industry into free fall. The problem for most technical writers is they didn’t become adept at becoming developers. So we’re now faced with a disconnect between documenting product and the developer side of the business.

What results is an excess of employees and contractors who struggle to plunder their way through the SDLC. The perfect technical writer credentials require the following skill set to bundle developer expertise with elegant help documentation:

  • Expertise using JIRA
  • QA and product testing
  • Building graphics and tables
  • Project management prowess
  • Collaborating with programmers
  • Creating HTTP help documentation
  • 4 years of AWS/cloud management
  • Capable of multi-tasking across the SDLC
  • Client/server experience with web services
  • 10+ years software development experience
  • Producing instructional video documentation
  • A profound understanding of agile development
  • A proven track record writing for Fortune 500 companies
  • The ability to work with diverse softwares (i.e. MadCap Flare, Adobe FrameMaker)

These skills are what cuts through the clutter between writing technical documentation and being a solution engineer.

Around 2010, many technical writers fell asleep at the wheel. As UI design and software documentation went into hyper drive, these writers were forever left behind lacking the necessary skills to keep up with the industry. Specifically in programming skills. Great API writers (such as myself) are experts at the mission-critical solutions.

Profoundly Simple API Documentation

Your API documentation project deserves a technical writer with vast expertise in website design, file management and single-source architecture formatting to take advantage of a streamlined work flow. Having been involved with many API documentation projects, I assure you I’m your best candidate to manage your entire project.

Writing for all users while understanding their skill sets is critical. The following Stripe developer API screenshot gives you an idea of the types of content programmers desire along with code examples. This is the type of API technical writing and integration I offer my clients:

stripe-docs

Output Options

flareTraditionally, technical writing required developing documentation for many output formats and devices (i.e. desktop, smartphone, tablet, Word, PDF etc.) by creating separate projects for each type. Not anymore.

With the robust functionality of MadCap Flare, you write once and output to the needs of your product and sales teams. Doing so streamlines production allowing multiple outputs of documentation from a single source of content rather than separate sources for each type of output.

Another benefit is you can import native file formats into Flare from other sources such as Word, FrameMaker, HTML and other types of help authoring tools. Doing so capitalizes on your current documentation file formats without the need to start from scratch.

Bridging the Gap Between Programmers and Users

Sometimes retail solutions aren’t always a good fit for your product documentation. In these cases, I strongly urge my clients to consider static help files. These are built on a Ruby Gem coded in Slate/Markdown.

Why static?

Speed. Although formerly considered a dated file format, they’re now used by many prolific companies. The programming aspect of this form of help documentation is a breeze to build. Since 2015 static files generated in Ruby or MKDocs are now considered the industry standard.

Forget about thick database file structures. They’re far too heavy and limit the needs of the perfect user experience.

Online Rules

The olden days of slogging through clunky PDF files as your user documentation are history. Every shred of your help system needs to be live. Face it. Programmers could care less about printed API calls and responses. Your API needs to talk the talk so your customers can be up and running connected to your API.

If your product people and sales teams demand printed output, tell ’em it’s time to step into the 21st century. That’s where premium HTML5 skills come in. You want a technical writer who can not only work with programmers documenting API source code but also bundle it all into a dynamic UI.

My Background & Skills

For nearly a decade I was a senior account executive for a national advertising agency. By 2007, I witnessed the explosive demand of IT documentation and chose to branch out on my own. Read my full bio and resume here.