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.
> 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.
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.
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.
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.
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.
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’.
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.
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.
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.
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:
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)
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.
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.
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.
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?
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.
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.