Technical writer with 10 years of experience. The way this post starts off talking about grammar is a yellow flag for me, if not red. Many developers/engineers get scared of technical writing precisely because of their fear of not using grammar correctly. Don't worry about that!! Just remember the cardinal rules of technical writing:<p>1. Know your audience. Talk to them. Look at their Stack Overflow questions. Analyze your documentation website usage. Run surveys. Make it easy for them to provide feedback.<p>2. Write for that audience's needs. <a href="https://diataxis.fr" rel="nofollow">https://diataxis.fr</a> is a great start because those 4 needs cover 90% of the most common developer needs.<p>Documentation is a profoundly effective way to help people. Don't worry about doing it perfectly. Just stay focused on being helpful and of service.
The pull request advice is strange in conjunction with several suggestions which boil down to "make PRs smaller".<p>> What types of changes does your code introduce to Appium?<p>Surely that would be obvious from the connected issue. If you suggest smaller PRs, it doesn't make a whole lot of sense to potentially combine feature changes, new features and bug fixes. Which makes that part of the template redundant beyond the exceptions.<p>> - [ ] Lint and unit tests pass locally with my changes<p>In the context of non-CI environments, I wouldn't trust anyone who signed this to begin with. In the context of CI environments, you can make this both uniform and automated. Why risk friction where there doesn't need to be any?<p>>Now, the programmer stereotype is that we’re poor communicators<p>Slight tangent: this stereotype <i>seriously</i> needs to die. I've been hearing this since studying CS, and I still see both clients and client-facing employees make basic mistakes they try to hammer out of students in year 1-2, while continuing to use this stereotype against programmers. It's become an excuse for client-facing and coordinating types to push ICs to adapt to them instead of the other way around.
Anyone got some favorite examples of great technical writing?<p>Stripe gets a lot of love, but I think React's tutorials are also wonderful: <a href="https://reactjs.org/docs/hello-world.html" rel="nofollow">https://reactjs.org/docs/hello-world.html</a><p>They did a stellar job of slowly building technical concepts before hitting you with bigger concepts like managing state.
Worth mentioning this great book on the subject published last year:<p><a href="https://docsfordevelopers.com/" rel="nofollow">https://docsfordevelopers.com/</a>
As someone who is a pretty good writer, with a long career, I've never experienced any project or workplace actually caring about my ability to write or rewarding me for it (beyond some lip service)
This is a great post. Wonderful cheat sheet for lots of various writing areas in tech.<p>There’s also lots of great content coming out of the Write the Docs community, including 10 years of conference talks: <a href="https://www.writethedocs.org/topics/" rel="nofollow">https://www.writethedocs.org/topics/</a><p>Disclaimer: I’m involved with the project, but lots of folks have done good work putting great content out there.
Technical Writing Courses from Google <a href="https://developers.google.com/tech-writing" rel="nofollow">https://developers.google.com/tech-writing</a> is good too.
My approach to tech writing (of which I have done a lot) is to pick an existing style you like and follow that. For example, when I was writing the docs for the API for a multi-site library we were providing I did it in the Win32 help-file format that MS used. This was a good format, and we were MSs auditors at the time so no-one could complain. I did it with a bunch of Word styles.<p>But of course content is far more important than format. IMHO, if you are not a good English writer, you are probably not a good dev.
>Comments can link back to the source<p>Big fan of using comments to point back to the source, that has saved me a lot of time of trying to figure out why my past self made those particular change
How much should someone documenting an API be able to use it?<p>I've been interviewing for a technical writer and some very experienced people, who seem to be greater at the job of Technical Writer, don't have basic coding proficiency.<p>If my org needs a writer who can code too, should we be trying to find a _developer_ who wants to write too? Coding and writing seem like different careers paths so are we looking for a unicorn?
See also:<p>Writing: A misunderstood activity | 144 points | 3 days ago | 64 comments | <a href="https://news.ycombinator.com/item?id=32043923" rel="nofollow">https://news.ycombinator.com/item?id=32043923</a>