5 ms·
Technical Writing for Developers
- infogulch 4y agoSee also: Writing: A misunderstood activity | 144 points | 3 days ago | 64 comments | https://news.ycombinator.com/item?id=32043923 https://news.ycombinator.com/item?id=32043923
- NithurM 4y agoThanks for sharing.
- nixcraft 4y agoTechnical Writing Courses from Google https://developers.google.com/tech-writing https://developers.google.com/tech-writing is good too.
- lelandfe 4y agoAnyone got some favorite examples of great technical writing? Stripe gets a lot of love, but I think React's tutorials are also wonderful: https://reactjs.org/docs/hello-world.html https://reactjs.org/docs/hello-world.html They did a stellar job of slowly building technical concepts before hitting you with bigger concepts like managing state.
- simonw 4y agoI really liked the Just README recently: https://github.com/casey/just/blob/master/README.md https://github.com/casey/just/blob/master/README.md
- sam1r 4y agoI was looking for a table of contents, and eventually realized the hint pointing to the top left. Really simple, minimal way to handle your table of contents inline, versus constantly updating links at the top of the page.
- azemetre 4y agoI think the Cypress documentation is absolutely great: https://docs.cypress.io/ https://docs.cypress.io/ One of the better things about cypress are how they create so many how-to guides for a variety of scenarios. Take implementing Cypress into a CI runners, they have guides on how to effectively use it nearly everywhere: https://docs.cypress.io/guides/continuous-integration/ci-provider-examples#Guides https://docs.cypress.io/guides/continuous-integration/ci-pro...
- deckard1 4y agoI've always been fond of Svelte. Their reference docs are great, but their tutorial really shines: https://svelte.dev/tutorial/basics https://svelte.dev/tutorial/basics. Each step provides a working example next to the documentation, allowing you to figure it out before clicking the "Show me" button for help.
- thfuran 4y agoMatlab has some pretty great documentation.
- joegahona 4y agoRelated: https://news.ycombinator.com/item?id=31859040 https://news.ycombinator.com/item?id=31859040
- ericholscher 4y agoThis is a great post. Wonderful cheat sheet for lots of various writing areas in tech. There’s also lots of great content coming out of the Write the Docs community, including 10 years of conference talks: https://www.writethedocs.org/topics/ https://www.writethedocs.org/topics/ Disclaimer: I’m involved with the project, but lots of folks have done good work putting great content out there.
- kaycebasques 4y agoTechnical 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: 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. 2. Write for that audience's needs. https://diataxis.fr https://diataxis.fr is a great start because those 4 needs cover 90% of the most common developer needs. 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.
- gaws 4y ago> Technical writer with 10 years of experience. What's an easy-to-remember trick for semicolon usage?
- xboxnolifes 4y agoDon't use it.
- wmeredith 4y agoHaha. Well said. My mother has a PHD in English Literature and has taught languages and writing in college for decades. She's also a book editor and an author with published works from picture books for children to graduate-level text books. She tells me that the semi-colon's primary use is to let the reader know that the author attended college. Just use a period.
- halfnormalform 4y agoAs T.S. Eliot said, great writers steal. That’s Kurt Vonnegut’s joke!
- lcnPylGDnU4H9OF 4y ago
- BlargMcLarg 4y agoThe pull request advice is strange in conjunction with several suggestions which boil down to "make PRs smaller". > What types of changes does your code introduce to Appium? 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. > - [ ] Lint and unit tests pass locally with my changes 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? >Now, the programmer stereotype is that we’re poor communicators Slight tangent: this stereotype seriously 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.
- tusslewake 4y agoWorth mentioning this great book on the subject published last year: https://docsfordevelopers.com/ https://docsfordevelopers.com/
- zabzonk 4y agoMy 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. 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.
- bryanrasmussen 4y agoAs 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)
- madeofpalk 4y agoI think that good writing is one of those things that people don’t consciously realise. Just like actually good UI.
- layer8 4y agoYou do it because you care about it. It's an instance of "be the change you want to see in the world".
- Timwi 4y agoIt would help motivation to have some allies though.
- k__ 4y agoThe moment I switched from selling code to selling text people started rewarding me for it.
- therealdrag0 4y agoHow do you measure lip service vs not?
- bryanrasmussen 4y agolip service - in interviews and onboarding talking about how they value documentation not - in actual work no time put aside for actually writing documentation.
- therealdrag0 4y agoSomewhere in the middle, my place definitely values good documentation. I’ve gotten kudos for it and I’ve had my manager bemoan poor docs written by other engineers as a sort of “doesn’t meet expectations” signal. We don’t explicitly put aside time for it, but it’s expected as part of normal work. Though mostly for upfront design. Less often for after the fact design.
- srdixon 4y ago>Comments can link back to the source 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
- turadg 4y agoHow much should someone documenting an API be able to use it? 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. 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?
- sirmoveon 4y agoHidding a treasure and having someone who doesn't understand geography create the map doesn't seem logical to me, but I've seen worst in the industry.
- layer8 4y agoDo you mean an HTTP API or a programming-language/library API? If the latter, definitely get a developer. If the former, they should at least be familiar with a formal language like SQL. They need to be thinking about the API in terms of the contract (preconditions etc.) it defines between the client code and the API implementation. That's rare if you never used a formal language.
- remoquete 4y agoNot a unicorn. What Microsoft calls “programmer writers” have always existed. They’re just more rare, and more expensive to hire.