The March Chapter meeting of STC San Diego was held at the Hera Hub Sorrento Valley facility in San Diego, on March 15, 2017. Susan Gallagher, a technical communicator with more than 30 years of experience in the software industry, gave a stimulating talk on the topic of documenting APIs (application program interfaces). The program was loaded with helpful information for attendees wishing to augment their marketability as technical communicators.
Following a period of informal networking with on-site participants, Chapter President Alice Brzovic led the business portion of the meeting, welcoming more than 20 participants including several new attendees. Everyone enjoyed an assortment of tasty and nutritious snacks and beverages.
President Brzovic reminded attendees that STC San Diego is hosting a banner design contest, and invited submissions from potential contestants. STC San Diego will display the winning design at all chapter events. The purpose of the contest is to secure an attractive and informative design that captures the nature and mission of STC San Diego. The deadline for submissions is May 1, 2017. Click here for further details.
Featured Program
Susan Gallagher introduced herself as a software industry veteran with decades of experience in creating, and training others to create API documentation. Having spent many years as a manager, Ms. Gallagher shared her experience in setting up documentation departments for software start-ups, and provided tips for creating successful documentation.
Participants gained a clear understanding of the basic features of API documentation and received prudent advice for creating such documents, as well as for building a good professional reputation in this area.
Ms. Gallagher peppered her talk with entertaining and sometimes humorous vignettes and anecdotes. The presentation was an engaging and informative product of long experience and wisdom.
Following are some words of advice from Ms. Gallagher on the various ways to produce timely and effective API documentation:
- Learn at least one programming language (JavaScript was recommended). This will help you to better understand your subject matter experts (SMEs), and to translate that understanding into concise English.
- Be diplomatic with the people you are working with, while trying to earn their trust. Understand that programmers may be perfectionistic in their work approach. Adjust your expectations and interactions accordingly.
- Engage programmers to begin assisting you in your tasks as early as possible. Variations in software production phases can occur rapidly and make it difficult for programmers to find the time to meet with you.
- Try to work closely with engineering managers, who are naturally invested in the success of your project and thus have powerful incentives to assign greater resources to you.
- Utilize the experience of technical sales staff to help translate your subject matter into non-technical English.
- Anthropomorphize verb phrases used to describe the functioning of inanimate objects. Write as if the code itself “does things”, even though human beings may be the actual initiators or cause.
Ms. Gallagher also gave some tips and tactics to use during interviews for API documentation jobs. She advised knowing which of the three types of API documentation the job entails:
- APIs buried in the programming language;
- APIs in the form of database schemas; and
- APIs as web service tools, such as Google Maps.
During the Q&A period, Ms. Gallagher offered to share writing samples and white papers on API writing with attendees, upon request. This level of access is just one of the many benefits of in-person attendance at STC meetings.
Hera Hub Sorrento Valley provides a venue for meetings and business activities. With its raised ceilings, unique features and functionality, the facility encourages an atmosphere of comfort and focus.
STC San Diego thanks our corporate sponsor MadCap Software for their support of this program.
