Recently, tech writer Tom Johnson gave a webinar on trends in the field of API documentation, which I attended because this topic is relevant for my dissertation. Click here to access the slides and the recording of the webinar.
The trends he found resulted from an online survey he conducted over the last two months. More than 400 participants completed the survey, including me.
Marginal note: I cannot remember how I came to know about the survey: it might have been via Twitter or through Tom Johnson’s blog when checking out this API usability article or that API Handyman podcast summary for my dissertation. In any case, I discovered the survey through activities related to the programme I study. Why is that important? Because it manifests how this programme connects me to the “real world” by a) introducing resources and b) building up practices and habits that c) will help me to sustain my professional development even after the programme will have ended. Which is important to me.
The survey asked technical writers who work in the field of developer documentation (which predominantly means API documentation: see slide 40) about their tools and workflows.
By that, the survey closed a gap that general tech comm research did not fill so far: to show how technical writers in the field of API documentation work. (Tom Johnson cites Saul Carliner’s TC Census and Scott Abel’s Benchmarking Survey as examples for general tech comm research.)
Having said that, the main insights for me—a technical writer trying to acquire more profound knowledge in the field of API documentation—were the following:
From slide 50:
- That feeling of “constantly drowning” is well-known (Tom Johnson hypothesised that people could feel that way). Still, it does not interfere with job satisfaction as the majority of the respondents seem to be quite happy with their jobs.
- It is not a flaw to spend parts of your working day learning new things. It is what everybody does! Most tech writers have a daily learning time between 20 to 60 minutes.
- Half of the tech writers that responded work as lone writers. So, I should consider myself happy to be part of a larger tech comm team. Only 14% of the respondents reported that they were, too.
From other slides or remarks throughout the presentation:
- Like me, many tech writers are somehow part of one or more engineering Scrum teams. (Slide 31)
- API documentation is mainly done “inhouse”. So, I figure that working for a software company and being a well-informed or even experienced API documentation tech writer should secure your job (for a while). | Slide 34
- Generating the doc artefacts from the code usually would be the engineer’s task. Tech writers then edit those documents. | Slide 44
- A new idea: Let the developers be the ones who contribute through pull requests. (So far, it was me, the tech writer, contributing to their repositories via pull requests.) | Slide 36
- Localising is a nightmare when using static site generators. You might rather want to use a Component Content Management System (CCMS). However, localising does not seem to be a big issue in the developer documentation world. (I am not sure whether it should be that way.) | Slide 27
- In the general tech comm field, tools that incorporate more than one function seem to be more prevalent than in the developer documentation field. For example, with a CCMS, you would be able to both shape content, do version control, and build the content to various outputs. The survey lists a lot of tools that could be a starting point when having to decide on a tool. | Slide 7
- Pain points for most of the respondents in the field are the same as for me: | Slide 51
- Struggling with the abundant technical know-how you need for the job
- Having sufficient time to accomplish the tasks
- Getting reviews from engineers
- And, a more general issue: Finding ways to address both novice and advanced users
- Another new idea (regarding list item 3, above): Invite engineers for a review meeting. Read out the docs (no more than 20 minutes). Let them comment on what they heard. Add their input to the docs (afterwards). Benefit: They do not have to annotate your docs; they do not even have to read anything. Possible outcome: Get reviews done in less time.
- Another thing that works well for lots of people: First, shape the content in a wiki-like tool or GoogleDocs-like tool where all parties can comment and annotate. After that, transfer the content to the target authoring format.
- And: I have to look into code review tools. | Slide 32
Are you a technical writer and familiar with issues like those mentioned above? Feel free to share your experience in the comments!
API docs and me 