Technical Writing for Developers
css-tricks.com
css-tricks.com
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.
What's an easy-to-remember trick for semicolon usage?
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.
Alternatively, just don't bother and use two sentences.
- What is the difference between a semicolon and a cat??
One has a pause at the end of its clause. The other has claws at the end of its paws.
- What happened when the semicolon broke grammatical rules??
It got two consecutive sentences.
—-
All that said, it’s usually better not to. There aren’t really many cases in modern English where a semicolon is necessary. And there are even fewer cases where a semicolon provides a more clear expression than two sentences. In practice, they’re most often part of really badly disjointed ‘sentences’.
My mother gave me my first car; it was an beautiful 2002 Honda Civic with a falling-off bumper and bald tires.
You could replace the semicolon with a comma thus:
My mother gave me my first car, a beautiful 2002 Honda Civic with a falling-off bumper and bald tires.
That feels a little more natural, but is harder to read accurately.
It's useful in legal and technical writing, but not necessarily great for everyday life. Personally, I don't really use semicolons; you may have different opinions on their usage.
It's basically an arrow in text.
this -> that
as opposed to a comma, which feels more like
this and also that
Can't a period do that?
You're not going to lose a reader over semicolon misuse if you're solving a problem for them.
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.
1 https://buttondown.email/hillelwayne/archive/beyond-the-four...
The two-axis diagram on diataxis is a great way to categorize documentation and all of them have different needs and indeed call for different voices. I have seen a number of projects where the only documentation produced is tutorials or itch-scratching posts for this one thing, and then when a feature changes somewhere you have a mountain of out-of-date information because everything was hard-wired to this combination of dependencies, versions and circumstances (whereas a manual could have been updated quickly and that would be that). And on the flip side, plenty of projects where there is a dense compendium for every detail and it's hard amid all the implementation details of the clustering gossip protocol versioning to find the little list of items you want to know to set the thing up to begin with - linked to the particular sections to read more about installation, configuration, backup, etc.
> 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.
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.
Really simple, minimal way to handle your table of contents inline, versus constantly updating links at the top of the page.
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...
not - in actual work no time put aside for actually writing documentation.
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.
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.
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.
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
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?
Writing: A misunderstood activity | 144 points | 3 days ago | 64 comments | https://news.ycombinator.com/item?id=32043923