Technical Writing for Developers(css-tricks.com)
css-tricks.com
Technical Writing for Developers
https://css-tricks.com/technical-writing-for-developers/
49 comments
> 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.
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.
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.
Grammar is not the most important thing, but it's hard to exemplify tone and voice without having the common language to talk about them and grammar is that language. I'm guessing the article starts with it because tone and voice is the most universal aspect, not because it's the most important aspect to technical writing. The rest are very hands-on details but that might not apply to everyone.
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.
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.
Over at his Computer Things newsletter[1], Hillel Wayne offers up some additional kinds of documentation worth adding to the four-document model. He lists five, but goes into detail on two: Conceptual Overviews are intended for beginners. They walk through all the concepts at a very high level. They provide no guide on “how,” avoid jargon, and can be understood by outsiders. Case Studies are examples that explore interesting or complicated problems in applying the concepts documented. An example is intentionally simplified, sometimes toy problems. A case study will show how to use the concepts on problems taken from real world uses.
1 https://buttondown.email/hillelwayne/archive/beyond-the-four...
1 https://buttondown.email/hillelwayne/archive/beyond-the-four...
> Technical writer with 10 years of experience.
What's an easy-to-remember trick for semicolon usage?
What's an easy-to-remember trick for semicolon usage?
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.
Alternatively, just don't bother and use two sentences.
I like to use a long dash instead. It gives the two statements more breathing room.
It's called an em dash. It's a dash the width of the "M" glyph.
https://www.thepunctuationguide.com/em-dash.html
https://www.thepunctuationguide.com/em-dash.html
No one really cares.
You're not going to lose a reader over semicolon misuse if you're solving a problem for them.
You're not going to lose a reader over semicolon misuse if you're solving a problem for them.
Dev with a flair for writing over here. Using semicolons is a good practice for separating clauses, especially if you're being verbose
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
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
I like using these two ‘jokes’. Neither of them are actually funny, but they help (me).
- 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’.
- 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’.
Don't use it.
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.
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.
As T.S. Eliot said, great writers steal. That’s Kurt Vonnegut’s joke!
Don't use it; or do, I'm not your English teacher.
I only use it as an upgraded comma. The options are red, green, blue; cyan, magenta, yellow, black; or black and white.
You mean in JavaScript? ;)
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.
> 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.
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.
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.
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.
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...
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...
I really liked the Just README recently: https://github.com/casey/just/blob/master/README.md
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.
Really simple, minimal way to handle your table of contents inline, versus constantly updating links at the top of the page.
Matlab has some pretty great documentation.
Worth mentioning this great book on the subject published last year:
https://docsfordevelopers.com/
https://docsfordevelopers.com/
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)
I think that good writing is one of those things that people don’t consciously realise. Just like actually good UI.
The moment I switched from selling code to selling text people started rewarding me for it.
How do you measure lip service vs not?
lip service - in interviews and onboarding talking about how they value documentation
not - in actual work no time put aside for actually writing documentation.
not - in actual work no time put aside for actually writing documentation.
Somewhere 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.
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.
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.
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.
Technical Writing Courses from Google https://developers.google.com/tech-writing 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.
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.
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
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
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?
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?
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?
Hidding 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.
Do 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.
Not a unicorn. What Microsoft calls “programmer writers”
have always existed. They’re just more rare, and more expensive to hire.
See also:
Writing: A misunderstood activity | 144 points | 3 days ago | 64 comments | https://news.ycombinator.com/item?id=32043923
Writing: A misunderstood activity | 144 points | 3 days ago | 64 comments | https://news.ycombinator.com/item?id=32043923
Thanks for sharing.
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.