How do I write, review and coach better English language in documentation?

Question

My job regularly involves writing and reviewing (in the form of pull requests) English prose in the documentation for our internal system, which solely faces other developers, in a strongly American firm spread around the world.

That writing falls into two categories - a documentation website, and documentation snippets in our API (e.g. Swagger docs for our REST API). I feel that both of these have a large effect on users' initial impressions of our system/product, and that initial impression is important to me. We do not have formal technical writers on the team, or indeed any in the firm that I'm aware of.

I'm a native English speaker, and I did OK in English in school. Over half of my team are not native English speakers. Obviously their English is infinitely superior to my skills in other languages, and they deserve credit for the English they do write and speak.

However, I'm often disappointed in the quality of English that I see in the documentation, including from native English speakers. I'm very comfortable reviewing code - drawing on static analysis, best practices, team guidelines, rules of thumb and personal experience. I'm significantly less comfortable reviewing documentation changes - I don't feel I have datum points or concrete evidence to rely on, just the gut feel that I've used ever since school. I often end up commenting on PRs with what I think the text should be, without much justification or logic.

On a bad day, that makes me question my own writing. Nobody ever comments on my English, so I don't get regular feedback like I do on my code. It also makes me feel that if I can't be sure of my own writing, I shouldn't be coaching junior developers on improving theirs.

I'm not sure if I'm just lacking the comfort and safety of a programming language and compiler - or whether there is genuine room for improvement here. How can I improve what I write, the constructive criticism I make on documentation, and ultimately the whole team?

Answer 1

You have probably found a few resources that improved your "programmer vocabulary," and made it easier to authoritatively discuss programming concepts. For example, you may have already had a gut feeling about classes that do too much, then you read about the single responsibility principle and it helped reify the concept in your mind.

Most other creative domains have similar resources. For writing, a style guide like the canonical Strunk & White fills that role. It spells out concrete rules about writing you may only have a gut feeling about. It will help provide that justification you feel you have been missing.

Answer 2

I feel your pain, it is sometimes hard to find people who are good in coding and have decent writing skills (even when they have to write documentation in their native language).

Improving someone's writing skills takes years. Hence, the only way I know to balance this is by trying to find someone who is good in writing (does not need to be a coder), and give them explicitly the task to review the docs on a regular basis. Maybe there is someone inside your organization, maybe you need to hire someone from outside for this.

(Personal note: I am really happy whenever someone corrects the errors in my answers here, since you surely observed I am not an English speaker for myself, and often overlook typos or grammar issues which a native English speaker sees immediately.)

Answer 3

Nobody ever comments on my English, so I don't get regular feedback

Here’s your problem. Nobody anywhere speaks English well enough that they don’t need feedback.

Find someone, anyone, and have them review what you write. Pay attention to what they say about it and how well they understand.

Don’t wait for this. Reach out and ask for help. Do it often. Don’t drop 20 pages on my desk asking for notes. Make me part of your process as you write. Don’t only ask me. Ask others as well.

Do this and soon people will realize you want feed back and will be more willing to provide it.

Answer 4

In Softwaredevelopment there is the practise of Pair Programming where two developpers do programming together to learn from each other especially asking "how would you" and "why did you do it this way" questions.

I would be glad to do something like pair-documentation with native-speaking professional.

On an website that helps to localize apps and websites for other languages it was interesting for me (as a native german) to see a-non-tech-german fixing my own german wording based on my app-s english translation. This was valuable for me to learn writing better german tech-docs. (better=less gramar errors, and easier to understand non-tech vocabulary)