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 the better your API documentation and integration is the faster customers onboard into your system.
The Problem With API Documentation
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 services 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.
A majority of the companies offering APIs rely on automated tools such as Swagger UI. It’s a great tool to automate the process of creating documentation. What are the drawbacks?
- Little freedom to customize the API doc UI
- Page scrolling is hardwired into the flow of materials
- Limited description fields in the documentation
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:
Output Options
Traditionally, API resources for end-users were limited to clunky PDFs or forever scrolling pages. Not anymore.
Reliance on PDFs is outdated. Granted, many financial institutions still resort to forcing customers to pilfer through reams of PDF documentation despite the integration drawbacks. If your company isn’t producing high-quality online API resources I promise you end-users roll their eyes reviewing your documentation.
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. Since 2015 static files generated in Ruby/Sinatra 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.
Which is Best?
It depends on the quantity of your API calls, documentation length and your end-users.
Option #1
If your current API documentation is in need of an UI upgrade serving a handful to thousands of users, I recommend a Ruby | Slate | Markdown stack. It’s designed to integrate the three-column format like Stripe API. Calls and response examples are coded directly into the UI backend.
In this scenario all UI styling and table of contents can be customized to suit your brand and integration needs. It’s built with a Ruby gem. Then edited inside an editor using Slate | Markdown code.
Samples:
Ideally, this solution is best built in a Unix environment. My preferred workflow is to manage the project in my office working remotely relying on BitBucket or Github for version control. Then integrate AWS as a second back up method.
The final .md files are exported as static HTLM files you can map to your IP framework.
Option #2
Thriving organizations with complex products and millions of users would be smart to convert to the Ruby/Sinatra duo. Why?
Reusable content can be embedded with Ruby elements into HTML output- Thwart against cross-site scripting attacks using harmless HTML entities
- Dynamic templates to control every aspect of functionality
- Three-column layout (like Stripe API) for supreme product elaboration
- Generation of lightning-fast pages minus the bulk of database architectures
- Freedom to build dynamic content with flawless simplicity
- Create session instances to personalize user experience
- Integrate encrypted browser cookies to support user preferences and behaviors
- Endless CSS styling options to match your brand’s style guide
- Hardwiring of scalable design eliminating reliance on third-party solutions