8 REST API Documentation Tips for Hardware Writers

Introduction:  I re-joined Oracle as a technical writer and content strategist in a storage systems development group over two years ago. In mid-2017, our team recognized the need to expand our content about a system’s evolving REST API. Like many veterans of hardware documentation, I didn’t know much about APIs, RESTful or otherwise. So I embarked on a journey to learn more.

This blog, written originally near the beginning of that journey (for a class) and updated since, presents helpful links and guidelines about REST APIs for former hardware technical writers like me.

Technology services based on the representational state transfer (REST) architecture or a RESTful application programming interface (API) are becoming more important for hardware developers and content developers to understand. Wait, what? Why do I have to understand programming stuff?

Well, I hate to break it to you, but programming isn’t just for coders any more. APIs in general – and REST APIs in particular – play an increasingly central role in the burgeoning cloud services market as well as the Internet of Things (IoT), according to Jennifer Riggins and others.

Because APIs provide a “level of abstraction” beyond the uniqueness of the “thing” itself, they enable a connectedness and interconnectedness that we mere humans have not seen from our refrigerators and vacuums before. For a perspective, review Alexandra Bowen’s still-relevant 2016 SlideShare set, and memorize her first answer to the question – Why APIs? “APIs provide the ability to glue and integrate services.”

REST API Concepts

Before you start to panic, remember that a REST API is based on the target’s “resources” – that is, the elements of the hardware itself as well as the data that journeys to and from that hardware:  disk drives, temperature sensors, network connections, user account data, and so on. These are concepts most of you are already familiar with.

Also remember that actual “programming” doesn’t really occur within the REST architecture. Activity is limited to configuring, retrieving, changing, or removing the target’s resources. These activities are controlled by the four main HTTP methods – GET, POST, PUT, and DELETE – which are common across most REST APIs. (For a description of the HTTP methods, refer to the RestAPITutorial page on the topic.)

If you need to get further acquainted or re-acquainted with REST concepts and terminology, review the Pearson eCollege tutorial on YouTube. And yes, for those of you who love Wikipedia, it offers a pretty good overview, too.

Guidelines for Documentation

Development of REST API content has become more standardized in recent years. Writers can assume a certain amount of experience and knowledge on the part of the audience, especially developers. Consumers of REST API documentation, in turn, expect to see content that meets them at their level. They may even expect the content to be organized in a certain manner or contain certain topics.

So as with any documentation project, start with understanding the REST API’s audience. To gather some tips about audiences, read Diana Lakatos’ blog “The Ten Essentials for Good API Documentation.”

Next, use the following eight guidelines to plan and organize your REST API content:

  1. Create a short Getting Started section that contains the following:
    1. The format for a fully qualified URI, including the base URL
    2. Authentication instructions
  2. Describe any unique request headers or unique use of request headers, or anything else unique about the API, including special query parameters.
  3. Include an alphabetical list of resources for easy reference.
  4. Provide details about each resource and endpoint; if need be, group the resources into logical categories for better management of the details.
  5. Provide lots of example requests and, as needed, example responses. Developers love code examples!
  6. Ensure that all your code examples appear in the programming language most often used by the target audience (for example, JSON).
  7. Include a list of status (HTTP) codes.
  8. Provide guidance for error-handling, as needed.

Going Further with REST API Documentation

For more tips on how best to document a REST API, review the 2016 SlideShare set from Marta Rauch of Oracle Corporation and read Diana Lakatos’ second blog “Ten Extras for Great API Documentation.”

Many RESTful API gurus point to Twilio’s REST API guide as a model for good API content. However, I prefer Twitter’s approach, which I find easier to navigate. For an example of hardware-specific documentation, see Oracle’s guide to the RESTful API for its ZFS Storage Appliance (written by a team other than mine).

Finally, as for which tools to use when you document your product’s REST API, almost any good documentation tool will suffice. That said, there is a growing trend among professionals to intertwine REST API development and documentation by using tools like Swagger – now associated with the OpenAPI Specification or OAS (refer to http://swagger.io/).

For some tips on how to evaluate REST API documentation tools, read the Algolia blog “Good API Documentation Is Not about Choosing the Right Tool.” For a review of available tools, read the article “Best Practices and Tools for Documenting APIs” by Mark Boyd of ProgrammableWeb, a news and information website dedicated to APIs.

Now you know as much or more than I did when I started my journey. Good luck to you!

Note: Mention of products or companies in this blog does not constitute an endorsement of those products or companies by me.

4 Rules for Business Email – Rule #4

OK. Serious case of writer’s block now for several months – not to mention side work as a contract technical writer.

Soooo, once again, here are my four rules for thoughtful and professional use of business email:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

As the rule list suggests, the fourth rule is really a result of conscientious use of the first three rules. Follow-up consists of – Ahem! <embarrassed throat-clearing> – not dropping the ball once it is in flight and also using good networking skills. Both stem from the well-known variation on the golden rule  – you know, the one that says it’s best to try to walk a mile in someone else’s Converse high-tops before you pass judgment.

Converse high top

Dropped-ball avoidance (just developing the sports metaphor here, so please don’t judge!) is a simple guideline to implement. It means that if you started the email string to begin with, you are responsible for closing it out. Typically, you can do that with a summary/next steps email back to all respondents on the string. Summarize the ideas they shared, thank them for sharing, and indicate what you and/or your team will do with those ideas (your next steps).

You can even follow up on the follow-up and go back to the email string after several weeks to inform everyone what steps/ideas you and/or your team have implemented.

You can also take follow-up in a different direction and examine the responses in the email string as jumping-off points for networking opportunities. (And yes, even those of you who are securely employed need to take advantage of networking opportunities.) Was someone included on the email string whom you have never encountered? Was someone on the email string especially critical of your team or their effort? Or did someone on the email string seem to struggle with understanding the topic?

All of these situations represent opportunities for you to reach out informally to the responder and talk – over coffee, over lunch, over Skype, whatever. Get some face time with him/her. Most of the time, you’ll be pleasantly surprised at how much you have in common with that person, and you might even find opportunities in which the two of you can collaborate. In fact, you might just find your next big opportunity professionally through that conversation. Or maybe just your next pick-up ball game. Either way, you’ve pushed beyond the keyboard and made a real connection. Good for you!

For those of you in the U.S., please have a safe and enjoyable Thanksgiving holiday!

4 Rules for Business Email – Rule #2

As a memory jog, here again are my 4 rules (guidelines) of business email etiquette:

  1. Be Polite
  2. Be Professional
  3. Be Clear
  4. Follow up! (which is an outcome, really, of the first three)

When I wrote about the first rule of business email – Be Polite – I suggested that you avoid email wars by requesting use of a different communication channel (phone call, face-to-face meeting, facilitated meeting, water pistols at midnight, whatever). But if you absolutely, have to respond by email, please, please remember that you are responding to a human being, not a machine. Most human beings these days – at least the ones I know – are doing the best they can while facing tremendous personal and/or professional challenges. So please remember that.

And if you can’t remember that (really? It’s so hard?), then remember that nasty-grams can live forever on someone’s hard disk drive. So be neutral, be sensitive, be smart and above all, be professional.

And that is our second rule of business email – Be Professional.

Email gurus Silberman and Johnson both remind us to watch the tone of our emails. Tone is a tricky thing. But believe it or not, it’s easier to moderate the tone of a written communication than it is sometimes to moderate the tone of our voice. (You can test this next time your cube neighbor douses you with a water pistol – how high and loud is your voice as you supposedly laugh it off?)

To moderate the tone of your emails, choose neutral words in place of more highly charged words. For example, refer to “status,” “open issues,” and “concerns,” not “debacles,” “problems,” or “mistakes.” While you might consider a shifting deadline to be an “issue,” it’s probably better not to refer to it as “missed” or “failed,” unless those words are used officially by your company or are generated by a software application – and you have your attorney sitting right next to you (holding a water pistol). People do take these labels personally, and you don’t want wade into an inter-departmental (or inter-company) conflict unnecessarily.

toe-water

Pushing into controversy myself a bit here (cue toe-in-water image), I’ll say that part of being professional is being sensitive to the person who was concerned enough about a topic to actually send you an email, especially if that someone is lower on the food chain than you. Being tough or clever or “above the fray” doesn’t always win the day; being appreciative and helpful can have more lasting effects (and remember, the email sender might not always be lower on the food chain).

(Note that I am not going to use the American idiom about catching flies with honey here, because, well, it’s gross and, besides, I’ve already used the term “food chain.”)

You know this, because you know it’s true in “real life,” too. I was reminded of this recently when I attended an evening public meeting in my community. Four professionals had formed a panel discussion on a specific topic. (I’ll be neutral here and not name the topic.) Toward the end of the evening, a woman in the audience stood up and asked specifically for help for her child. She was obviously emotional (though not overly so) but very sincere in her request. Not one of the panel members responded. Yes, you read that correctly, not even one.

Finally (to the relief of everyone), another professional in the audience stood up and offered to talk with her after the meeting. (At the same time, he acknowledged that he wasn’t sure that he was the best person to help her.)

How hard was that? Which one of the six people involved in this situation was the most professional, in your opinion?

OK, now I’ll take my toe out of the water, foot out of my mouth, water pistol away from my head, whatever, and talk about one last pet peeve about professionalism in business email. And that has to do with loooooooong email chains – the kind that cross weeks and even months on the calendar – or emails with multiple or hefty attachments. For the love of Mike, people, keep the context but ditch the heft! Mike, by the way, is the poor IT guy responsible for your company’s overtaxed email server.

So the last sub-rule is about professionalism when responding to a business email that’s been circulated through half the world: Be smart. Before you hit Reply All, make sure that all of the right people are on the distribution list; then delete and summarize any of the simple intervening replies (say “the following people on the distribution list have already agreed”; then list them) and keep the original email as close on the page to your response as possible. Believe me, people will thank you (including Mike).

And I will thank you to keep reading my blogs on email etiquette (smooth, eh?). Next topic is business email Rule #3 – Be Clear.