3 ms·
I write technical guides for people who are not native speakers. Using simple vocabulary is easy, but using simple grammar is not. Here's a recent article I wr
by nicbou 6y ago
I write technical guides for people who are not native speakers. Using simple vocabulary is easy, but using simple grammar is not.
Here's a recent article I wrote. It should give you an idea of what I mean: https://allaboutberlin.com/guides/car-insurance-germany https://allaboutberlin.com/guides/car-insurance-germany
There are a few things I would add to this:
---
▶ Your readers are here for information, not entertainment. Get to the point.
▶ If a paragraph answers a question, the first sentence should be the tl;dr. Highlight it if necessary. [1]
▶ Use formatting to make skimming easier. Users don't read documents from start to finish. They are looking for specific answers. [2] I spent a lot of time tweaking my website to be more readable.
▶ Use can (optional), should (recommended) and must (mandatory) consistently. "It's ill-advised to do this, because ..." >>> "You should not do this, because ...".
▶ Avoid run-on sentences. Generally, that means maximum one comma per sentence.
▶ Start with the "if" part of the sentence: "If you are over 60, you are not eligible". It lets people skip sentences that don't concern them.
▶ Avoid expressions and idioms as much as possible. "If you're feeling under the weather, stay home" >>> "If you don't feel well, stay home".
▶ Avoid ambiguity between sentences: "The cat sits in the house. It is old." >>> "The old cat sits in the house".
▶ Use commas generously. It makes sentences easier to digest. I'm a big fan of the Oxford comma.
▶ Use Hemingway [3] to catch some of those mistakes
---
In other words, DON'T BE CLEVER. It feels a lot like writing software that will be maintained by novice programmers.
Simple language is really important, especially if you deal with the general population. Some people don't read well. Some people don't speak English well. Some topics are confusing enough on their own.
[1] https://allaboutberlin.com/guides/anmeldung-in-english-berlin#can-i-do-my-anmeldung-at-a-hotel-or-airBnB https://allaboutberlin.com/guides/anmeldung-in-english-berli...
[2] https://allaboutberlin.com/guides/how-to-get-a-german-freelance-visa https://allaboutberlin.com/guides/how-to-get-a-german-freela...
[3] http://www.hemingwayapp.com/ http://www.hemingwayapp.com/