Posted on 2 Comments

12 Steps To Getting Started as a Consultant

Most people think it’s difficult start a career as a business consultant. I used to think the same in my early 20s when I started in IT. In retrospect, I should have made more efforts to establish myself as a consultant earlier; the benefits certainly outweigh the downsides. As luck would have it, I was forced into a consultancy role when I lost my 9-5 job. Time to learn to hustling and bring in business. Harvard Business Review refers to it as The Hustle Strategy. More on that later. Continue reading 12 Steps To Getting Started as a Consultant

Posted on 8 Comments

How To Write Technical Documentation For APIs

One of the threads on LinkedIn is how to write technical documentation for APIs. It’s been many years since I’ve documented an API (Java & Oracle) so if you have any thoughts on the best way to do this, then please jump in.

An application programming interface (API) is an interface implemented by a software program to enable interaction with other software, much in the same way that a user interface facilitates interaction between humans and computers.

What is an API?


APIs are implemented by applications, libraries and operating systems to determine the vocabulary and calling conventions the programmer should employ to use their services. It may include specifications for routines, data structures, object classes and protocols used to communicate between the consumer and implementer of the API. Wikipedia

Concept

An API is an abstraction that defines and describes an interface for the interaction with a set of functions used by components of a software system. The software that provides the functions described by an API is said to be an implementation of the API.

An API can be:

  1. Generic — the full set of API that are bundled in the libraries of a programming language (e.g. the standard Template Library in C++ or the Java API)
  2. Specific — meant to address a specific problem, like the Google MAPs API or the Java API for XML Web Services.
  3. Language-dependent — available only in a given programming language. It is only available by using the syntax and elements of that language to make the API convenient to use in this context.
  4. Language-independent — written in a way that means it can be called from several programming languages. This is a desired feature for a service-oriented API that is not bound to a specific process or system and may be provided as remote procedure calls or web services.

For example, a website that allows users to review local restaurants is able to layer their reviews over maps taken from Google Maps, because Google Maps has an API that allows it. Google Maps’ API controls what information a third-party site can grab, and what can be done with it.

“API” may be used to refer to a complete interface, a single function, or even a set of multiple APIs provided by an organization. Thus, the scope of meaning is usually determined by the person or document that communicates the information.

API Guidelines

Here are some sites that offer guidelines and examples of API documentation.

Twitter’s API Documentation

Twitter has done a great job documenting its API and breaks out all the different component.

“The Twitter API consists of three parts: two REST APIs and a Streaming API. The two distinct REST APIs are entirely due to history. Summize, Inc. was originally an independent company that provided search capability for Twitter data. The Streaming API is distinct from the two REST APIs as Streaming supports long-lived connections on a different architecture.” http://apiwiki.twitter.com

Tips for writing API documentation

What advice would you give to someone writing their first API document set? What mistakes do technical writers make when approaching this area?

FYI: Twitter API: Up and Running: Learn How to Build Applications with the Twitter API

Posted on

How Technical Writers Can Move Further Up The Food Chain

Do you feel loved? Many technical writers feel unloved. They feel they don’t get the respect they deserve. I hear this on LinkedIn and Facebook: “people don’t respect the work I do.” Well, if that’s the case, here are a few ways to get more respect and move into a more rewarding career. Continue reading How Technical Writers Can Move Further Up The Food Chain

Posted on 3 Comments

How Advertising in User Guides Could Work

Putting advertising in user guides may seem rather flaky at first, but it could work. Here’s why. One of my ‘pet projects’ is to connect the lines between Sales and Technical Documentation. To me, they both serve the same purpose. Serve the customer. While they both start at different points, the end goal is the same. Unfortunately, these two departments rarely work together. Let’s take a look at how we can fix this. Continue reading How Advertising in User Guides Could Work

Posted on 14 Comments

7 Ways for Technical Writers to Re-invent Themselves & Demonstrate their Value

You’ve just been fired. The Technical Writing Dept is closed. What do you do?  This is a fact of life for many people today. Indeed, there is now a real fear that US technical writers will continue to lose their jobs to offshore companies, e.g. India & Poland. And it’s true; it’s the shape of things to come, I’m afraid. But rather than moan about it, let’s look at what you can do to re-invent yourself and find new, lucrative opportunities. Continue reading 7 Ways for Technical Writers to Re-invent Themselves & Demonstrate their Value

Posted on

Is the STC Value For Money?

STC LogoSarah O’Keefe (Scriptorium) discusses STC’s new dues structure: Dues are going up; Printed publications are no longer included in basic dues; No chapter or SIG membership are included in the basic dues.

She adds that while reaction is largely negative, she finds value from her STC membership and gives some examples and reasons to join/stay with the STC. I have to confess that I disagree her on most all points. Continue reading Is the STC Value For Money?