1. API technical writer technology & UI/UX skills
- 1. API technical writer technology & UI/UX skills
- Poor API documentation examples:
- US Government
- Common API technical writer hiring gaps:
- 2. API technical writer PDF amnesia
- Why Not PDFs?
- 3. API technical writer superpowers
- 4. Front-end development experience
- Stunningly simple API doc examples
- Why upgrade your API documentation?
- 5. Project management prowess
- 6. They eat structure forbreakfast
- 7. Flexibility
- 8. Creative With Output Options
- Swagger UI
They possess experience in UI/UX design not only as an API technical writer but also understanding an exceptional user experience.
Too few tech writers are diving into the deep end of user engagement. Although, they’re hardly to be blamed. 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. Mostly driven by REST (although financial institutions have relied on SOAP for decades), they connect services. At this writing there’s nearly 30,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.
Before we can continue, we need to demonstrate the difference between a good API resource and a bad one. They come in many flavors.
Poor API documentation examples:
- Clunky PDF file (no UI available)
- Too short and absent language bindings
- No table of contents
- Dated UI appearance
- Pagination is lame
- One color code examples
- Looks scattered
- Usability is totally absent
- No logical navigation
- 10-mile long scroll
- Way too much grey
- No table of contents
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:
The usual culprits:
- 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
- Technology has evolved so fast on the developer side surpassing documentation writer skills
2. 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…
The struggle using them is gaps in usability. It’s far from brain surgery to craft developer end-user 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.
For example, a mega-sized financial company I consulted 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.
Why Not PDFs?
End-users (developers) want fast integration resources. Having to peruse through a 346 page PDF is a waste of their time. But it gets worse.
- What happens when you have change log updates?
- Should developers ignore older versions of your PDFs?
- 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. Quick and easy for certain. Yet, they’re not explicit nor user-friendly. Writing APIs understood by 5th graders is the fuel which keeps your customer integration machine firing on all cylinders.
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 formal structures.
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…
Providing users with large paragraphs went out with disco. Instead, creative UI/UX design of documentation takes eye strain into consideration. Then blends relevant help materials with a more elegant and pleasing user experience.
Balance is something learned rather than taught. PayPal’s API documentation is built with simplicity. It begins with design at the wireframe level. Then evolves into seamless usability.
Defining supported parameters should be clear and concise. Documenting mission-critical connection values are essential for API configuration. Especially for complex calls.
Tables work well and a perfect example is illustrated in the Clearbit API resources page. Displaying parameter attributes using columns provides a structured framework for users.
Dynamic functionality begins with a beautiful API UI designed for consolidation of user documentation. Then weaves logical navigation into the fabric of complex subject matter.
The gold standard is Stripe’s API documentation page. They’ve built subtle transparency guiding users to the most relevant integration resources all within one screen instance. The days of long scrolls are long gone.
Building a clear division between endpoint connection examples and instructive API documentation is the litmus test of clarity. When done well, the UI/UX offers profound simplicity for users of all skill level.
The long-form API documentation winner is obvious in Swagger’s resources. They’ve cornered the market on dropdown toggles controlling however much detail users require to integrate connections.
Logical division of left sidebar categories should be hierarchal. The concept isn’t radical nor difficult to implement in the design phase of your UI resources.
In the following lob.com example, you’ll see a seamless flow of categories used to connect related API resources. Building logical navigation into your page provides users fast action to pinpoint their relevant documentation materials.
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.
4. Front-end development experience
The best API technical writers have a background in programming. Especially using tools such as:
- CSS | HTML
- 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 user help connecting to them.
It’s a common challenge in organizations of all sizes. My approach is to cut out delays by building the UI myself.
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
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.
5. 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.
6. They eat structure forbreakfast
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:
- Web | Mobile
- IOS | Android | IOT
- Objective C | Swift
- C# | JAVA | Node.js
- PHP | Python | Ruby
- Click to Call
- Call tracking
- SMS | Voice
- Browser calls
- Warm transfer
- Call forwarding
- IVR phone tree
- Instant lead alerts
- Automated survey
- Employee directory
- Account verification
- Dynamic call center
- Workflow automation
- Appointment reminders
- Two-factor authorization
- IVR screening & recording
- Conference and broadcast
- SMS two-factor authorization
- SMS & MMS marketing notifications
- Masked phone numbers with PHP and Laravel
- Masked Phone Numbers with C# and ASP.NET MVC
As you can see, Twillio’s API documentation provides a brilliantly structured framework. It’s no surprise they’re dominating the communications industry.
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.
The last trait I believe is required is having a passion for being flexible. I’ve worked on teams where there was an obvious need to tap writers for product testing. Some teams ignore the manpower yet as writers, we certainly have the time.
Genuinely curious, technical writers should be ready to dive into product testing for two reasons:
- Exposure to upcoming subject matter functionality
- Becoming a valuable contributor to the developer team
In this market, hiring for one refined skill set is common. However, it’s costly.
8. Creative With Output Options
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.
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.