API technical writer technology & UI/UX skills

They possess experience in UI/UX design. As an API technical writer, they thrive helping build exceptional user experiences. Can they edit or manage the publishing of API reference documentation? I hope so.

These days static sites are a smart choice. Docusaurus and Gatsby are my favorites.

• Too few tech writers are diving into the deep end of user engagement.
• Engagement includes color, big, bold text, and a simplified UI.
• Structured content blocks are critical to ease eye strain.
• Our industry has propelled itself into hyperdrive on the developer side.
• The fallout has been in documentation.

Something many writers aren’t fully dialed into is that the entire Internet is one big API. Most are driven by REST (although financial institutions have relied on SOAP for decades). At this writing there’s nearly 40,000 public APIs. Industry experts estimate there’s four times as many private ones.

Highly-qualified API technical writer candidates have vast experience building user interfaces (at least they should). Whether it’s with WordPress or another CMS, they understand the nuts and bolts managing online content. At some companies, they don’t want writers dabbling inside the code base. Obviously, this is to mitigate risk. However, the struggle many organizations are facing is the balance between API source materials and how they’re presented to end-users.

If you have content creators already on your team, integrate them into product testing. It’s part of the SDLC which will give them vast exposure to UI versions. I’ve worked with documentation technical writers who were able to upgrade their skills adopting usability testing as part of their assignment to pitch in building better product.

Hiring an API technical writer is no walk in the park. Honestly, I’ve interviewed many of them and often their skills vary. Read about my interview process vetting candidates. There’s a handful of us working in the industry. Recently, I was contacted by a recruiter. He told me I was one of 30 he found on LinkedIn residing in the U.S. with robust experience.

Common API technical writer hiring gaps:

• Traditional writing skills don’t dovetail well with new standards.
• Recruiters endorse API writer candidates who have limited experience.
• Writers resist pouring through code examples writing API calls and responses.
• There’s not many documentation training programs for writers to learn about APIs.
• Testing should be a requirement using Postman or Shell.

API technical writer PDF amnesia

Industrial-strength API technical writer candidates are blessed with not remembering their addiction to PDF outputs. Forget about PDF documentation. It’s deader than doornails and here’s why…

First, you can’t embed Google Analytics code in a PDF. So how do you know anyone read it? You don’t. Therefore, if you want to harvest user metrics of engagement, it needs to be published online so you can monitor usability.

The struggle using PDFs is the gaps in usability. It’s far from brain surgery to craft developer help guides.

But the missing component is designing a user interface which displays the API calls and responses with code examples.Then document the mechanics of endpoints and parameters along with code bindings.

Traditionally, this process has been managed using the long-form structure. You know, many long PDFs with endless scrolling. Check out the Salesforce getting started guide. 199 pages is mighty long. Salesforce publishes all of their help documentation online and offer users a copy of it in a PDF.

A mega-sized financial company I consulted with in 2016 was stuck in the stone age. Shockingly, their API technical writer was documenting the source code inside of Microsoft Word docs. Then exporting them into lengthy PDFs. It worked well for her. Unfortunately, it was difficult for new users to figure out which PDF was the most recent.

Big mistake.

Why Not PDFs?

End-users (developers) want fast integration resources. For example, forcing developers to peruse through the SalesForce 1700+ page PDF is a waste of their time. But it gets worse.

1. What happens when you have change log updates?
2. Should developers ignore older versions of your PDFs?
3. Which is the correct PDF for them to refer to when looking for help?

Don’t forget helping someone connect to your API equates to happy customers. Thereafter, revenue. So why are so many API technical writer teams relying on dated authoring tools? Usually it’s poor advice offered by developers or DevOps. They scramble to engineer a solution which conforms to their programming team.

Often their decision is to rely on PDF documentation as the old fallback solution. Quick and easy for certain. Yet, they’re not explicit nor user-friendly. Gosh, don’t forget about the lengthy request and response code examples.

3. API technical writer superpowers

High on the list of skills is being a superhero defender of online user documentation.

As recent as 2007, online help resources were MIA. Even companies such as Apple still relied on churning out mountains of manuals. Those days are nearly as dead as doornails.

I’ve worked with a handful of enterprising team members who’ve made the leap from old school formatting to new kid on the technical writing API documentation block. It requires a sincere interest abandoning clunky publishing efforts.

Face it. Many of us grew up with printed subject matter. Who can forget the metric tons of Encyclopedia Britannica editions we pilfered through searching for help? Well, for those of us over the age of 30.

Passion is the litmus test to making the jump.

Way back in 2009, I saw the opportunity in my own career. Curious about converting my passion for writing to managing online documentation, I dove in head first. Initially it was limited to CMS management of help documentation.

In 2012 I noticed the trend using static pages were more prevalent. No longer were companies relying on bulky, heavy database website architecture for their API help guides.

But the problem is the technical writers didn’t get the memo…

Shedding the safe confines of MS Word isn’t something they teach in writing class. Quite the contrary. Nor do some writers consider themselves tech savvy.

Some boast about the benefits of exporting Word documents to clean HTML. It’s a nice idea. Hardly practical when you’re building dynamic API documentation.

The culprit is always formatting issues and CSS. Word offers limited architecture. So the clunky workflow isn’t suitable for streamlined migration of content into the UI.

World-class API documentation should be a blend of help resources combined with a dynamic UI.

Ones like these…

Believe me when I tell you these types of interfaces are design for extreme usability. Too many companies consider the API documentation as an add-on task of their SDLC.

Often the reasons are:

• Poor planning
• Lack of oversight for end-users
• Time demands to release APIs as quick as possible
• Very few qualified API technical writer candidates to work inside the source code

Technical writing API documentation should be planned in the early stages of the project.

Front-end development experience

The best API technical writers have a background in programming. Especially using tools such as:

• CSS | HTML|Markdown
• JIRA | Perforce
• Middleman | Unix
• GitHub | Bitbucket
• Swagger | Postman
• Ruby | Slate | Markdown
• Command line programming

Why are these programmer skills considered the gold standard? Often programmers are good at creating API frameworks and testing. Few can bridge the gap between the endpoints and writing endpoint use cases.It’s a common challenge in organizations of all sizes.

I’ve worked with a handful of large financial institutions managing and developing their API UI documentation. Usually they’re closed APIs.Safeguarding their integration guidelines from the public restricts using Swagger or Github to host their API materials.If you’re reading this far, I’m referring to static pages developed using Ruby | Slate | Markdown.

Stunningly simple API doc examples

• Stripe
• Scale
• Sony
• Best Buy

Why upgrade your API documentation?

Your end-users are desperate for clarity.

Likely, you’ve heard from customers or your product people complaining about your current API resources. If so, welcome to the club. Every month I’m contacted by project managers frantic and ready to upgrade their API integration help content.Their #1 complaint is that their writers lack an understanding of non-reference documentation. If you haven’t brushed up on your own API resources, there’s two parts:

• Reference docs which document elements such as code examples, classes, endpoints and responses
• Non-reference materials provide introductory help to your API along with task-based steps of integration

Writing API documentation is one of the most sought-after skill sets in the technology industry. Especially for product and service providers with millions of customers.

Project management prowess

Exceptional API technical writers have proven experience with project management tools.

Whether it’s JIRA or Perforce, they should be adept monitoring sprint progress. Doing so empowers them to connect with the SDLC workflow.

I’ve worked on a few projects where the writers were excluded from project management meetings. The PM dictated the writer’s role wasn’t essential to product. Hmmmm…if they’re not essential, what are they? Every shred of product development and API integration should be old hat to your writers.

The consequence of excluding API technical writer teams from development are a lag in product knowledge. Far too many writers bypass the hardwiring of your back end while awaiting subject matter to draft. It’s counterintuitive to crafting profoundly simple end-user documentation.

On the other hand, I’ve led projects where writers were required to integrate their writing projects into JIRA. In these cases, we had thousands of requirements. So managing the endless documentation of these items was best served following the exact same process developers use to track sprint progress.

Military-grade API technical writers should be exceptionally invested in all aspects of project management.

They eat structure for breakfast

This is the granddaddy trait of all. For example, what if you have a monster API resource such as Twillio.com? Their documentation provides help for the following resources:

As you can see, Twillio’s API documentation provides a brilliantly structured framework. It’s no surprise they’re dominating the communications industry.

Beware.

Expert technical writers don’t need to fully manage this type of UI architecture. However, they do need to be well-versed understanding the backend tools which publish these types of robust API docs.

That’s why having at least five years of front-end developer experience is a must.

Contact me…

Creative With Output Options

Swagger UI

Publishing your API docs can often be a mixture of easy or complex. Most developers don’t want anything to do with the publication process. At least if it involves customization of the UI.

Swagger UI is a good resource if you’re looking for a third-party solution. I’ve served on a few teams where Swagger UI was a no-brainer. Mostly for the automation benefits generating open API documentation.

The challenge is when you want to integrate a three-column format (read why you should) along with your company branding styles. One project I collaborated on was a private banking API. Swagger didn’t offer the customization options required to serve their end-users. Another issue for my client was their need to offer API response descriptions in full detail. Swagger doesn’t offer unlimited description fields. My experience is despite the fast generation of the docs, Swagger relies too heavily on the long form scrolling UI.

So why do so many software teams use Swagger? It’s a quick solution to a complex requirement. But what if you want to serve your end-users with profoundly simple using a three-column format? You’ll need to build a custom UI. I’m a strong believer that the industry relies too heavily on developer tools for API documentation. It’s perfect for them. Not so with users who may need plenty of handholding walking them through the steps of integration.

Readme

Another self-contained UI solution is Readme.io. They’re a fairly decent all-in-one provider for documentation. Think of them as a WordPress-like band-aide for APIs. The challenge for many dev teams is they usually have integration standards to follow mandated by DevOps.

For example, many financial institutions are restricted using third-party solutions due to PCI compliance. Despite Readme integrating with Swagger (at this writing anyway), if your API is private, there can be risk. The other pain point is their level of UI customization is limited. I’ve worked on a few corporate API projects where they needed unlimited customization to match their brand styles.

Never forget it’s the user experience which defines whether or not your API documentation will make their lives easier. Having worked with developers for many years, I feel they’re too hardwired adopting help frameworks suitable for their teams. It’s not a criticism. Instead, it’s a consequence of their expertise building to requirements.

So the question is simple: are meeting build requirements more important than a simplified user experience? It can be a touchy subject due to the demand balancing release schedules with teaching API users to get connected quickly. But if you ask relationship managers and sales teams, they’ll tell you the real story, “Customers aren’t thrilled with our API help documentation.”

Are you ready to upgrade your API docs? Get in touch with me about your next API technical writer project.