I've been a technical writer for ~8 years (3 at a startup, 5 at Gooble). I don't know Apple's situation but here's my guess:
> Is the documentation team too small? (Likely.)
Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful.
(As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about)
I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).
Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up.
(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)
> technical writing is almost always understaffed
> it's really hard to show a causal link between the docs we create and developer success
Amen to that. IMO good documentation is incredibly valuable, but not in a way that aligns with business priorities. At my current job, we hear, repeatedly, that our documentation is poor, and that we need to improve it. Execs echo this sentiment, but the status quo doesn't budge.
Internally, we have about a 10:1 engineer:tech writer ratio (in a small-ish org--I assume the gap is even wider in larger orgs), and the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
Engineer-drafted documentation often isn't great, unfortunately, for several key reasons:
- Writing software is very different from using software. Engineers often don't use their own products, and writing about something you don't actually do is hard.
- It's very easy to omit details that are important for novices when you are an expert. Engineers usually have a great deal of knowledge about their own software in their brain already, because they wrote it, and cannot magically forget everything they know when asked to write documentation for someone who doesn't have that knowledge already.
- Writing effective, clear prose is hard, especially when writing about complex technical subjects for an audience with varying skill levels. Engineers don't spend the bulk of their time writing prose, and it's often not their strongest skill.
Personally, I have a mix of both skillsets because of a weird career path, but while I actually like writing documentation and am arguably better at it than writing software, there's no good reason to pursue that path: I can easily get double the salary in an engineering position as I can in a writing position, despite being a rather mediocre engineer. So I do software engineering :shrug:
It's also very hard to get in the minds of the developers who rely on the API/tool and create documentation that mirrors their mental models, background, language usage, etc.
With Chrome DevTools (I wrote/maintained pretty much all the official docs for about 3 years) it was a bit easier because I had a huge repository of direct user experience to draw from: the thousands of Stack Overflow questions about DevTools
> the writers are all generalists, covering every product from top to bottom. In practice, this means that engineers are asked to draft the bulk of documentation, and the writers scramble to at least copy-edit it.
This seems like an organizational/staffing mistake. In other engineering orgs you'd see these roles filled by applications engineers, who dogfood while evangelizing the product and writing its technical documentation. Ambiguity or questions are handled by conversations with the engineers that built it.
I do think hiring application engineers with that kind of job description is one solution, but so is having a larger number of technical writers so they don't need to be generalists.
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback.
Whilst this is great, I think most people perceive documentation differently. Rarely does documentation delight me in the sense that I'd leave feedback. Generally, my interaction with documentation is one of "It works as expected"; "pretty bad but I still managed"; or "bad, didn't help, or didn't exist".
The thing that has the most effect on my is the last one. That is what will get me to drop a system. The first one "it works as expected" comes with a little but of surprise and delight. But, perhaps paradoxically, even though it surprises me, it still only meets my expectation. With a 'was this helpful' prompt, I'd need to click "it was helpful" on every successful search of documentation I ever do. This seems still too unremarkable for me to explicitly mention it was helpful.
Yup I know it's a tall order / unrealistic but I'm just trying to provide context as to why documentation might be systematically underfunded (lack of causal chain proving its value). Your response is totally understandable but it also demonstrates why the situation probably won't change any time soon.
establishing a DSAT metric is still powerful. Lifting a key feedback metric from "this is bullshit" to "this is ok" is something you can sell management on
To be honest, was this helpful button is rather vague and I usually ignore it because it doesnt seem to be the right question or rather its a request for feedback I don't know helps me or not.
I advocate for "was this page helpful?" being the standard question across docs sites because ultimately it does reflect the purpose of documentation (to be helpful in one way or another, which usually means helping you complete a task or understand a concept) and because using the same question on all sites enables us to benchmark and compare. I once ran an A/B test on the same page where 50% were prompted "was this page helpful?" and the other 50% were prompted "was this page useful?" and the results were different to a statistically significant degree which suggests that even minor rephrasings skew the results, so we need to all use the same terminology.
> its a request for feedback I don't know helps me or not
Yes I'm aware that readers aren't incentivized to respond which explains why it's rare to get higher than 5% response rate. This situation is a microcosm for documentation's overall problem: we can't find incentives for people to voluntarily and consistently confirm the value we provide and we don't have any other means to prove the causality.
"Part of it is that it's really hard to show a causal link between the docs we create and developer success"
Yep, high traffic to a dev doc web page is ambiguous. Is it because it's really good? Is it because it's bad and people keep coming back trying to understand it? Or is the documentation fine but the API being documented is just hard to use?
We get 1-5% response rates (which is normal; I've done this on a few sites now) but we have enough scale where we're getting enough feedback that I can use the data to identify the worst docs. The basic methodology is to prioritize the pages with the most pageviews + lowest helpfulness scores. Of course there's a risk that we're prioritizing our work based on data that isn't indicative of our overall audience and due to the general nature of the question ("was this page helpful?") we also don't know how exactly the doc is unhelpful but in practice it's usually easy to make an educated guess (e.g. one of the Lighthouse guides is very low rated, and when I checked on it recently I discovered it's just a stub with very little guidance; so the educated guess is to add more guidance to the page; and then a few months from now I can see if the ratings have improved). Another good pattern is to provide a freeform textbox for feedback. The only reason we don't have that is because Gooble considers it PII and I have to jump through hoops to store that data properly.
As someone who was in the so called "DevOps" position for years, I'm slowly becoming tired of asking management for "give me a technical writer, even half-time, instead of another dev/ops person" :(
I'll admit that I'm pretty bad at formal documentation myself, but I've been wanting to improve that lately. So as a technical writer do you have any suggestions/links to material for learning the trade or even some sort of formal training courses for professional development that I can pass to my employer?
> I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links
And when you do this, DO NOT serve up the feedback form/popup from some advertising domain, otherwise developers with ad lockers (many, if not most) won't even see it.
> Is the documentation team too small? (Likely.)
Documentation is weird because there seems to be widespread agreement among developers about how lacking it is (and conversely I think it's safe to say how important it is for job success) yet technical writing is almost always understaffed, no matter what size company you have. Part of it is that it's really hard to show a causal link between the docs we create and developer success. I know it seems silly but that's why I've been advocating for getting those little "was this page helpful?" links at the bottom of pages, followed by an opportunity to provide freeform feedback. If developers started using those consistently and leaving testimony about how the docs helped them it would be a lot easier to prove the value of docs. This is especially true when you operate at a big, platform-level scale, as is the case on https://web.dev (what I work on) and these Apple API docs. Pageviews give us a rough idea of the demand for certain ideas but don't tell us anything about whether our docs are actually useful.
(As an aside, in some situations it's easier to justify the technical writing team's existence; e.g. your technical writer specifically creates docs in response to support requests and the support team is able to just link customers to the docs rather than re-answering the same question over and over; or you have access to "customer's" code and are able to show that they are following the best practices / use cases you mention and avoid anti-patterns you warn about)
I'll leave with a suggestion because I don't have a horse in this race. If this situation is so bad; your best option might be to create a community-managed MDN-style resource for the Apple ecosystem. I would suggest focusing it on 1) API reference documentation and 2) examples (MDN puts the examples within the API reference pages, that would probably work here).
Another route could be more of what these people are already doing: make a lot of noise until Apple realizes how bad the situation is. I imagine if you can prove that you're leaving their platform because the situation is so bad, that might wake them up.
(No disrespect to Apple people; I know how tough this situation is; just trying to provide constructive feedback for the broader community)