Grammar is an essential part of technical writing to create clear and grammatically correct articles. To be sure that you’ve written everything right, upgrade your skills.
Grammar is an umbrella word refers to English grammar, syntax, word choice, punctuation, capitalization, spelling, and style. Grammatical topics are actually wildly more complicated than I can cover.
This post suggests common shortcuts and best practices that I followed personally to write technical blog posts in English for worldwide audience.
- Use acronyms properly - Spell out the full term and then put the acronym in parentheses like Progressive Web App (PWA) then use PWA going forward. Skip expanding popular acronyms into full term like HTML, CSS, JS.
- Prefer active voice - We mentally convert passive voice to active voice while reading so better to use shorter direct active voice.
- Prefer clear sentences - Pick the right verb and the rest of the sentence will take care of itself, reduce generic weddings, optionally minimize certain over-exaggerate adjectives and adverbs.
- Prefer short sentences - Focus each sentence on a single idea, convert some long sentences to lists, eliminate or reduce extraneous word, reduce subordinate clauses.
- Prefer cohesive paragraphs - Write a great opening sentence, focus each paragraph on a single topic, don’t make paragraphs too long or too short.
- Use appropriate punctuation - Some punctuation marks are easy to master, some are confusing. The most flagrant way a writer demonstrates contempt for his readers is by ignoring punctuation altogether. A close second is the abundant use of the punctuation marks.
- Use bold words sparingly - Bold is used to highlight the text and capture the readers’ attention. The bold tag is used for strong emphasis. When you feel like emphasizing something, you need to first consider using the italics, only use bold text if you are not satisfied by the emphasis the italics did to your text.
- Consistent titles and headings - Whether you use title cases or sentence case for titles and headings, you better be consistently with style.
- Prefer second person - Use second person (you) rather than first person (we). Second person pulls the reader into the action. Especially if you write in the present tense, second person allows the reader to experience the story as if it’s their own.
- Be aware disrespectful or offensive words - Some words might be interpreted differently in different cultures. They may sound innocuous to you, but please don’t throw around these seemingly innocent words and phrases.
- Prefer same style of wording in a series of items - Widely varied wording is distracting and potentially confusing to readers.
- Prefer worldwide communication - It’s usually safe to assume your content will be read in many countries and by readers whose primary language isn’t English. Avoid idioms, colloquial expressions, and culture-specific references.
- Capitalize proper nouns - Proper nouns are one of a kind—unique people, places, and things. Capitalize proper nouns wherever they occur. Don’t capitalize common nouns unless they begin a sentence or the situation calls for title-style capitalization. Capitalization should not be used for emphasis (use underscores or italics for that, or for really important things).
Simple grammar tends to be easy to read and understand, like a conversation. That basic grammar you learned before you were 12 is probably just right for most technical content.