Session 1 Summaries – 24 January 2015

Session 1 Topics For Discussion

1. Documenting APIs

Scribe: Karen Aidi

Facilitator: Fred Jacobson

Top Takeaways:

  • Knowing a programming language is virtually essential (Start with Python or an easy lang)
  • Know the industry and the domain language to communicate effectively
  • Look at Web APIs – particularly REST APIs – look at Twitter and Flickr APIs as documentation models
  • Using your language write a small code snippet
  • Account for the range of experience of your audience


Fred started out with asking what the participants wanted to get out of the session. Most were interested in how to break into API technical writing. There were many themes and questions throughout this session:

  • What is API documentation?
  • What is good API documentation?
  • Do I have to be a programmer to write API documentation?
  • Who writes the code samples?
  • What is the difference between a human writing the API documentation versus “autodoc” reference manuals?
  • How do I get started as an API writer?

There was a general acknowledgement that there are many API writing jobs. And, these jobs want a person to know several programming languages: such as Java, JavaScript, PHP, C++, Python, just to name a few. A lot of job descriptions seem to reference REST APIs, so those seem to be very much in demand right now.

What is API documentation?

There were both newcomers to documenting APIs as well as experienced API writers in the group. Newcomers to documenting APIs, asked for a brief definition of what an API is. An API defines how two pieces of software talk with each other. There are many types of APIs: APIs to extend an existing software system as well as Web APIs.

Sarah Maddox gave two examples of Web Service APIs: Flickr and Twitter. As an example, she mentioned that a WordPress blog uses the Twitter API when the blog includes a twitter feed on a web page.

A participant asked: does a (web) service mean the same as an API? No, it doesn’t. There are different types of APIs: web services APIs might be REST APIs or other APIs, while some APIs may extend an existing system by using a Java API.

What is good API documentation?

Tactics for producing good API documentation include: interviewing project managers, internal users, and other users besides just the engineers, and looking at marketing documentation to get an overview.

In an agile environment, look at the user stories, which will help the writer with use cases. Learn about the development process by observing engineering in your own company.

Do I have to be a programmer to write API documentation?

Do you need to be a programmer (coder) to write API documentation? Not necessarily, but writers should know what programming is, should learn a programming language, and experiment with code snippets themselves. Fred mentioned that a good programming language to start with is Python.

To get some practical experience, one participant recommended using Postman,

an extension to Chrome. You can go from Trjullio or Twitter and start making some calls with Postman.

Who writes the code samples?

Does the writer write code samples or does the programmer write them? Yes and no and it could depend on the job.

One writer shared that he has never had to actually write the code samples. Usually, he leverages code from QA. Another tactic might be for the writer to create a story to provide a context for the examples throughout the documentation.

Programmers want to get their job done, so they love code samples that they can use. In some cases, the programmers will write the code samples, particularly, the more involved code samples.

What is the difference between a human writing the API documentation versus “autodoc” reference manuals?

Automatically generated or “autodoc” reference manuals are automatically generated from the code source. The programmer may write the first cut descriptions. However, the human still needs to be involved because there is a gap between the reference manual and the task that a programmer needs to perform. This is where writers can add a great deal of value. Auto-generated reference manuals may be laden with jargon or may not explain terms or pre-requisite tasks that are useful to all levels in the target audience.

How do I get started as an API writer?

How does one go from government type of work to API documentation? The analogy given was a car analogy. If you are in the left lane and you want to move into the right lane, you signal that you want to make a lane change, and you start to steer yourself in that direction. Find an API that you like, write some code, build an example, and then publish. Learn one language, learn the principles. What language to learn? Python was mentioned by Fred as a language to start learning.

How does one deal with intellectual property (proprietary API) versus public APIs or REST APIs?

Understand the audience. Use conditional text to prepare two different deliverables: one for an internal audience and one for an external audience.

2. Scripting FrameMaker

Scribe: Joanna Broadbeck

Top Takeaways:

  • Scripting FrameMaker is used to automate repetitive task or tasks that must be performed across many files
  • There are two methods for scripting. ExtendScript is a Javascript-based language provided by Adobe and is free. FrameScript is a 3rd party solution more similar to VB Script
  • It isn’t easy to get started. There are several consultants available. See their websites, free samples


What is it?

MIF-save in this format to go to older version, to get rid of errors, “MIF washing”

ExtendScript (in FM12) vs FrameScript

Scripts can do all things you can do manually, via script

Rick Quattro does scripting

You must know FrameMaker document model; scripts can read external file

Scott does FDK development

Where’s the good documentation? Adobe FM Scriptmaking Guile

Developer Portal.

Sec West Street Consulting – FDK developer that created many samples

Resource: Adobe FrameMaker Scripting Guide

Inter-application communications are possible FM<–>other adobe products

Script types: Notification scripts, startup scripts, etc

What would you use it for?

  1. Doc conversion and apply templates (you can make a map for that)
  2. Use scripts for automated formatting (anything you can do manually)
  3. Create PDFs (lots of books)
  4. Carpal Tunnel prevention!
  5. Reduce the time it takes to do repetitive activities
  6. Huge search/replace
  7. Master books (including books within books) – website has plug-ins, including free
  8. Apply tags to many files
  9. Restructuring docs based on styles to go into DITA
  10. Assigning attributes to conditions during a conversion

How much need is there for scripting FrameMaker? It’s not difficult, but … West Street Consulting = Russ Ward does sessions on scripting in various languages; Scott Prentice – just spoke about going from FM to DITA

Semi-related discussion: Companies are using Word again. Easy to record a script. if developers must edit, companies use word.

ExtendScript only works on Adobe products – Not for MS products

Download samples form West Street Consultants, Frame Gurus, Adobe Forums

3. Keeping up with industry trends

Scribe: Wendy Shaffer

Top Takeaways:

  • Safari Books Online
  • Slideshare
  • Techwr-l list
  • Conferences
  • com
  • Code Academy


Self-teaching: safari books online

Slideshare is a great resource for presentations

industry trends: Writing style (Simplified Technical English), Mobile, Video, Social Media, Personalization, Pushing Marketing Language in Tech doc


Learn from your developers

Conferences (video tutorials)

Code academy (for python, html, others)

Blogs, news sites

4. HTML5

Scribe: Greg Urban

Top takeaways:

  • HTML4 compare to HTML5 (HTML 4+1)
  • new tags- a lot more tags
  • attributes – many more
  • cool features – audio tag, video tag, will pull in screen elements, including video player and IO player
  • advantages: no more div soup


HTML5: API, video tagging, looping video

new tag – Lots more – easier to understand

Recap of HTML development, interoperability usage of divs

HTML5 responsiveness depends on CSS, JavaScript

Data elements can move, flexible attributes not limited

efficient for video and audio tags

Advantages: no longer have to have a div

5. Metadata and categorization strategies

Scribe: Joan Lasselle

Top takeaways:

  • can be simple or highly complex
  • managed informally or managed by a specialist
  • Helpful to have specifically trained specialist to help you get started
  • Used to find topics/content (internal); use to help customer find data (external); use to track status of content


Link with library science

The Accidental Taxonomist – introductory book , IA Institute

Few using today

Each topic – pick from a list

hard to come to a decision about what metadata

What do you want it for – to find topics in future to manage customer experience

Determined by queries

Most use to manage topics internally

Should not be redundant with the content

Keyword metadata – how do keywords relate to SEO

Metadata then keywords

metadata categories

Taxonomy – Define the context, what is the set of data you are working

who for

why do it

6. Job search techniques

Scribe: Ryan Young

Top Takeaways:

  • Job boards – loud but low quality
  • LinkedIn – higher quality, more work
  • Referrals – highest quality, most work
  • Make your own job – a lot of work


Everyone in the job market

Job boards – loud but low quality – sponsored, there probably isn’t an 100$ fit for any job; the best fit is around 80%; sentient, articulate, fearless, and audience-aware

LinkedIn/Indexed/Simply Hired – higher quality, more work – costs $400 for 30-day to post a job, often just looking for future candidates (sometimes); listings != opportunity; better to know someone; LinkedIn is best – you know who is responding; “Post and pray”; LinkedIn is honest and refreshed often, others are dishonest or not trusted;

Referrals – highest quality, most work – companies like internal references better; most reliable and safest – internal referral bonuses are high;

Make your own job – a lot of work – find solutions to problems, consultants make more, even introverts can do it, and if not, get a “puppet” to be the face and voice

postings are “wish lists”

Ask people to prioritize job descriptions

Take job descriptions and create table comparing requirements to your skills

Teach yourself skills

Companies don’t post contract opportunities – once these go to an agency, the rate goes down

LinkedIn: use search + term – rich summaries and titles, use word cloud to get terms “writer” not “info developer”

Be forthcoming in summary about what you want to do to avoid marketing/social media jobs

Read job description that interest you: if you don’t have the skills, learn them. Start teaching yourself.

LinkSV: Search jobs by zip, search jobs here, contact companies via LinkedIn

Recruiters: self-interested sales people, who work for client – not you; won’t remember you; Short attention span: explain things to them using the job description. Tell them how much you need to earn.

Resumes need to clearly demonstrate how you map to job requirements. Needs to be clear why you are applying to this job

Project resumes sometimes seen as liabilities because they might be “mashs”

Employees want to see chronological resumes & escalating responsibilities

2-5 years/job is a good duration

Free conferences -> the trade show portion

Volunteer in tech writing organizations