|
> You wouldn't expect TWs to dabble in the prod codebase. I actually think you should expect TWs to dabble in the prod codebase. At least for TWs writing docs for developer products. To write the Chrome DevTools and Lighthouse docs I frequently looked at the implementation to figure out how things actually worked. From time to time someone would file an issue on the docs and we would realize it's really just a flaw in the product that can be relatively easily fixed. I couldn't get engineers to prioritize the work but if I put in a fix myself someone would review/approve it. Rather than jump through hoops to update the docs to reflect this quirk, it was often faster to just put in a fix in the product itself. > if you're going to hire people who are great technical writers, why would you have software developers (who are by definition not going to be as good TWs as the "real" TWs) also do it As mentioned in the last paragraph, a difference between our viewpoints is that I do expect TWs to dabble in the codebase, so perhaps it's not a stretch to imagine how your business might improve if you also work in reverse (engineers dabbling in docs). In practice, the real "synergy" happens when engineers get into the doc creation process early and often. For example, a writer might create a very rough draft of a guide and ask the engineer to review for technical accuracy only. (Edit: as dragonwriter mentioned, it's often much more efficient for TWs to go to engineers for technical information, rather than deciphering it out of code, PRDs, etc.)). Or, have engineers write the very rough draft themselves and have the TW turn it into a polished document. Another approach is when the engineer is very motivated to improve their writing, and they take on writing a doc, and the TW works with them step-by-step to polish it into a usable doc. My hunch is that for any given org, you'll only have a minority of engineers who want to improve their writing like this, but when it happens it should be prioritized/rewarded/encouraged. One area where it might make sense for engineers to mostly own the docs is API references. There should be an expectation that any changes to the API should also require a doc update. Another useful expectation would be to have engineers review docs after making a change to the product and make sure the required documentation update is at least logged as an issue somewhere. Over time you tend to see engineers engaging with TWs more substantially ("I was reviewing the doc for change X and noticed that the overall organization of the guide seems a bit off..."). I'm not arguing that engineers should take on all the docs work themselves, just as I'm not arguing that TWs should take on all major software development. But from my experience there's a lot of benefit to having each role systematically take on a bit of ownership of each other's domain. |