4 ms·
I think a small source of confusion/varying opinions here is that this is from the perspective of a technical writer. Technical writers are usually producing do
by opportune 3y ago
I think a small source of confusion/varying opinions here is that this is from the perspective of a technical writer. Technical writers are usually producing documentation for external users (author mentions "customers") as their key deliverable.
At least for me, I'm not too bothered by the docs I write looking a little unpolished or going out of date every now and then. Only a couple dozen people are likely to ever read it, it's not a big deal if I miss something because they'll know I wrote it and reach out directly if they need clarification, and as a corollary I'm mostly optimizing for "make it so explicit that they don't need to reach out for help, but not so verbose that they give up before reading it and reach out for help". Everyone knows it's a best-effort side task and you're not being held to a high standard - for guide-like documentation, just show the critical path most people care about and hope for the best.
When I consume official external documentation though, screenshots are a smell, especially in the case of "[having a screenshot] For every step in a task." You can't just message the writer to ask for clarification if you deviate from the happy path. So documenting the user-journey with screenshots instead of the functionality no longer works, because you have no real escape hatch as a confused user.