Scenario: What to say about trends
A survey of my own...
- Focus only on dev docs
- 50 questions, 10 min.
- Mostly multiple choice
- Promote on my blog, Twitter, Linkedin
Survey results are public
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.
What is your primary authoring tool for creating documentation?
Freeform answer: What specific tool(s) are you using to create documentation?
|Confluence 46 instances
||Oxygen XML 34 instances
|Flare 35 instances
||MS Word 26 instances
|Hugo 27 instances
||Jekyll 25 instances
|Custom 16 instances
||Redoc 15 instances
|Google Doc 15 instances
||Sphinx 12 instances
|Framemaker 11 instances
||MkDocs 11 instances
|Gatsby 10 instances
||DocuSaurus 8 instances
|Readme 8 instances
||Paligo 7 instances
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.
- 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.
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.)?
- 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.
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?
- 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.
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
- 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.
||52% male, 46% female
||200+ different companies listed
||31% humanities, 28% engineering, 15% tech comm
|satisfied with job
||38% agree, 37% strongly agree
||34% lone writer, 2-4 writers 31%, 5-7 writers 12%
|most affinity towards
||WTD 39%, none 31%, STC 14%
|time spent learning
||30 min 28%, 20 min 27%, 60 min 14%
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