How Trends in <API Documentation> Differ from other Tech Comm Trends

By Tom Johnson / @tomjohnson
idratherbewriting.com

Slides available at
idratherbewriting.com/slides/devdoctrends.html

Scenario: What to say about trends

Existing current research?

A survey of my own...

• Focus only on dev docs
• 50 questions, 10 min.
• Mostly multiple choice
• Promote on my blog, Twitter, Linkedin

Participant statistics

Survey results are public

https://www.questionpro.com/t/PGhS9ZgCFE

See also: My writeup

Note: Processing, organizing, analyzing, and interpreting data is hard, even from multiple choice answers. I'm not an expert at this, but with 400+ responses, trending answers are hard to ignore.

Main survey categories

1. Tools
2. Outputs
3. Processes
4. API
5. Profile

1. Tools

What is your primary authoring tool for creating documentation?

Freeform answer: What specific tool(s) are you using to create documentation?

If you write content in a text editor, which text editor do you mainly use?

What's the most common source format used in your documentation?

In general, do you follow a "docs-as-code" approach, where you treat documentation similar to how developers treat code?

What software do you use to create graphics, screenshots, or other visuals?

Other: Draw.io (29), Gimp (17), Inkscape (15), Photoshop (15), PowerPoint (11), macOS (11)

What platform do you use to host and publish documentation, especially to provide continuous integration/delivery (CI/CD)?

Which kind of computer do you use?

How do you manage your content?

Reflections: Tool categories

Reflections: Tool use different

• No longer a single tool for authoring, review, and publishing. Many different tools are used in different scenarios/purposes. See Jamstack examples.
• The "tool" is ambiguous. Is it the editor? Is it Markdown? Is it the static site generator? The build and deployment mechanism? Internal review tools?

Reflections: Not always a "tool"

• Some people working in dev doc work only in code annotations and OpenAPI specs. There is no "authoring tool" apart from their IDE (e.g., IntelliJ IDEA)
• Many working in Markdown treat it like DITA — the tool is irrelevant because support for the format comes from so many platforms/tools.

Reflections: Tools influence content

Emerging picture

• Writers use Confluence/Word/Google Docs for early content development.
• They assemble and build docs using a static site generator (Hugo, Jekyll, Gatsby, MkDocs) working in Visual Studio Code as the editor.
• They publish using a docs-as-code model with Git to trigger a CI/CD model deploying on company's own infrastructure.
• There's also a decent amount of wikis, Oxygen XML, and MadCap Flare use.

2. Outputs

What's the primary output format for your documentation?

Do you currently create video tutorials or screencasts?

If you aren't creating video/screencasts, why not?

Main reasons: No bandwidth, tech constantly changes, and no one has asked for video.

Do your docs plug into a larger developer portal?

Do you localize your documentation?

Do you usually generate out PDFs for documentation?

Did you play a significant role in developing/evolving your company's publishing solution (e.g., maybe you helped design the site, workflows, strategies for content re-use, stylesheets, etc.)?

Emerging picture

• Writers primarily create web content that fits into a larger developer portal.
• The writers often help shape and build both the publishing solution and portal.
• Localization, video tutorials, and PDF aren't overwhelmingly produced but do constitute about 1/4 of the output.

3. Processes

How do you interact with engineering scrum teams?

How do you review your docs prior to release?

Does your doc publishing solution have continuous integration / continuous deployment (CI/CD)? For example, when you push to a certain branch, do builds kick off on a server and push the docs out to production?

Do you outsource any documentation to an offshore authoring agency?

Do you have a style guide for your team that standardizes terminology and conventions regarding style, grammar, and syntax?

When you collaborate with engineers, how do the engineers contribute?

Emerging picture

• Writers participate on scrum teams, sometimes in limited capacity.
• They review docs using the same tools engineers use to review code.
• Engineers contribute through pull requests or through wikis.
• The publishing process is streamlined through CI/CD.
• Most content is generated within the company rather than outsourced.

4. API

Does the documentation you work on usually involve some kind of API?

What is the most common type of API you work with?

If you're creating REST API documentation, do you use the OpenAPI specification?

How do you render the OpenAPI spec into documentation?

Do you primarily create the OpenAPI spec manually or do you auto-generate it from code annotations?

Who generates out the OpenAPI specification at your company?

For reference docs for native library APIs (e.g. Javadoc or Doxygen), who creates this content?

What are the most common programming languages you need to know in your role with docs?

Which of the following new or trending technologies are you documenting (or will likely be documenting) this year?

Main answers: Machine learning, big data, AI, data privacy, security, IoT

Emerging Picture

• Almost invariably dev docs involves an API, usually a REST API.
• When documenting the REST API, most use the OpenAPI spec.
• Both writers and engineers collaborate as they generate out docs using Swagger UI or a custom parser.
• The most important languages to know are JavaScript, Java, and Python.

5. Profile

General demographics

What are the biggest challenges you face in working with developer docs?

Main answers: Technical know-how, time/bandwidth, getting reviews, addressing both novice and advanced users

Contact

Tom Johnson
— idratherbewriting.com
— @tomjohnson
— [email protected]