[HN Gopher] Technical Writing for Developers
___________________________________________________________________
Technical Writing for Developers
Author : makaimc
Score : 86 points
Date : 2022-07-15 17:31 UTC (5 hours ago)
(HTM) web link (css-tricks.com)
(TXT) w3m dump (css-tricks.com)
| kaycebasques wrote:
| 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:
|
| 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 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.
| rpdillon wrote:
| > The way this post starts off talking about grammar is a
| yellow flag for me, if not red.
|
| I thought the post was full of useful guidance. I'm not sure
| what you mean with the comment about flag color. I tend to use
| terms like "red flag" to mean "Something is seriously amiss;
| perhaps I should look elsewhere for good advice.", but that
| doesn't seem to apply here: covering grammar in an article
| whose audience is people who write as part of their profession
| seems completely appropriate. Conversely, I'm not sure I agree
| with the advice that it's OK to simply not worry about it.
| Perhaps it depends on the experience level the guide is
| targeting. There are certainly more important aspects to
| technical documentation than grammar!
|
| FWIW, I end up tripping over others' grammar errors far too
| frequently for my own comfort, though. When I've asked, it's
| not that they don't know in most cases, just that they don't
| think it matters. I tend to care both because it reads more
| smoothly, and because it indicates they paid attention to their
| work (something I value greatly). Not definitive, but certainly
| a strong signal.
|
| That said, my grammar is rarely perfect, and I strongly agree
| that focusing on helping others is the real objective here.
| kaycebasques wrote:
| The post is called technical writing for _developers_ and
| then the post starts off with the very topic that intimidates
| and discourages a lot of developers / engineers: grammar.
| Putting it at the top implies it is the most important idea
| (see the journalism principle of the inverted pyramid for
| rationale). That is the red flag. My usage of that term is
| the same as yours. My point is precisely to not let worries
| about incorrect grammar stop developers from trying to create
| documentation. Focusing on grammar is textbook "missing the
| forest for the trees". There are so many more important /
| more fundamental ideas in technical writing than grammar. Of
| course you will eventually need to learn grammar to become an
| expert technical writer.
| gaws wrote:
| > Technical writer with 10 years of experience.
|
| What's an easy-to-remember trick for semicolon usage?
| infogulch wrote:
| Don't use it; or do, I'm not your English teacher.
| xboxnolifes wrote:
| Don't use it.
| wmeredith wrote:
| Haha. 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.
| lcnPylGDnU4H9OF wrote:
| Consider when you have two distinct statements that are
| related but the former does not necessarily lead into the
| latter; a semicolon is appropriate in such an instance.
|
| Alternatively, just don't bother and use two sentences.
| mcbishop wrote:
| I like to use a long dash instead. It gives the two
| statements more breathing room.
| wmeredith wrote:
| It's called an em dash. It's a dash the width of the "M"
| glyph.
|
| https://www.thepunctuationguide.com/em-dash.html
| BlargMcLarg wrote:
| The 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.
| zabzonk wrote:
| 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.
|
| 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.
| NithurM wrote:
| Thanks for sharing.
| turadg wrote:
| How 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?
| srdixon wrote:
| >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
| nixcraft wrote:
| Technical Writing Courses from Google
| https://developers.google.com/tech-writing is good too.
| lelandfe wrote:
| Anyone 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
|
| They did a stellar job of slowly building technical concepts
| before hitting you with bigger concepts like managing state.
| deckard1 wrote:
| I've always been fond of Svelte. Their reference docs are
| great, but their tutorial really shines:
| 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.
| simonw wrote:
| I really liked the Just README recently:
| https://github.com/casey/just/blob/master/README.md
| sam1r wrote:
| I 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 wrote:
| I think the Cypress documentation is absolutely great:
|
| 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-pro...
| tusslewake wrote:
| Worth mentioning this great book on the subject published last
| year:
|
| https://docsfordevelopers.com/
| bryanrasmussen wrote:
| 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)
| madeofpalk wrote:
| I think that good writing is one of those things that people
| don't consciously realise. Just like actually good UI.
| joegahona wrote:
| Related: https://news.ycombinator.com/item?id=31859040
| ericholscher wrote:
| This 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/
|
| Disclaimer: I'm involved with the project, but lots of folks have
| done good work putting great content out there.
| infogulch wrote:
| See also:
|
| Writing: A misunderstood activity | 144 points | 3 days ago | 64
| comments | https://news.ycombinator.com/item?id=32043923
___________________________________________________________________
(page generated 2022-07-15 23:00 UTC)