Identify your audience, speak their level of vocabulary (technical, linguistics).
Identify the purpose of the written material, the objective.
The purpose of written text is to inform and educate. It should focus on two goals:
- Readability
- Comprehensibility
Writing is not the act of taking data, concepts, ideas and knowledge and transposing them into words. The true responsibility of the author is to convey such things in a manner that the reader accurately perceives what the author perceives.
Written text must be accurate, do your research, even on simple concept or definitions. Most people are not authorities on things, so recalling only from memory is not technically accurate.
Warnings! come first. Provide warning that result in damage or danger before any instruction.
Clearly declare what is required from the reader.
For example: The reader should know basic JavaScript and how to use NPM Modules.
Most important stuff comes first, while you have the reader's full attention.
Sentences must be concise and clear (less is more).
- Avoid long sentences, keep them to an average of 16 words.
- A sentence must be complete in itself.
- Avoid several short sentences.
Do not use many punctuation or commas.
- A single comma is good, to break a long sentence.
- Several commas should be used when listing items.
We had tea, cake, and cookies.
Use a comma to separate two independent clauses:
It was a long walk to the store, and it was getting dark.
Do not join two sentences with a comma, a common mistake. When unsure, use a period and check the sentence is complete and can stand on its own.
Avoid recursive sentences, that refer back too many times to a subject.
- Using 'it' or 'this' several times or after introducing a second subject can be confusing to the reader.
- Do not force the reader to push and pop things from their mental stack!
Watch out for dangling modifier, it is a modifier used in text without a target. The following sentence fails to specify what is fully constructed.
When fully constructed, the initialization sequence will start.
Above we leave the reader asking, what is fully constructed?
Avoid verbose padding (fillers) and redundant repetitive text (repeating to enforce learning is fine, but change up the delivery).
Do not use big words to show off linguistic abilities.
Avoid the use of contractions, for example:
BAD GOOD
--- ----
It's It is
Don't Do not
When to use the following emphasis, ranked by importance.
-
Bold: To Introduce a definition, emphasize something, or to warm.
-
"Quotes": What someone said, when copying a reference.
-
"Bold": Bold quote for code artifact.
-
Backticks: Do not use. Usually used for code artifact, use bold text in quotes. -
Italic: Do not use. Barely noticeable, usually used to introduce a new term, use bold.
Always use an active-voice. It conveys the actor performing an action.
Words, "by", "was opened", "is deleted" are usually passive.
- Passive: Lock files should be deleted (Sounds suggestive).
- Active: Delete all lock files (Sounds like a directive).
Write everything in the "present" tense, in the now! Computers and software have no past or future.
Use an Instructive-voice (non-person perspective), it is gender neutral. Use Second-person voice as a fallback alternative. Avoid use of "I" and first person voice.
- First-person: I deleted the log file before running the script.
- Second-person: You should delete the log file, before running the script.
- Third-person: She deleted the log file, then he ran the script.
- Instructive-voice: First delete the log file, then run the script.
Notice how the Instructive-voice is both instructing and detailing steps to be performed.
Tips on person's perspective:
- The Second-person voice is directing the reader to do something.
- The Active-voice is stating what must be done, ignores who needs to do it (I, me, you, he, she).
Avoid use of negation when possible, like, "not possible", better, "impossible".
Do not use double negative, "not less than". Instead use "greater than".
- Use 'an' with nouns that start with a vowel (a, e, i, o, u).
- Use 'a' with nouns that start with a consonant.
- A truck
- An application
- A mouse click
An should be used before a silent "h"
- An honorable mention
- It should take an hour
For a bullet list, do not add a period at the end, unless the text is a proper sentence, also capitalize.
Provide introducing text before presenting an image or diagram.
Use images and diagrams to convey an idea or concept, do not overload a diagram and make it look too busy.
For complex diagrams, build it up in steps with increasing complexity, or focus on separate area on concerns.
An ideal paragraph will have 3 sentences, it can vary between 3 to 5 sentences, but no more.
Flow of a paragraphs in a section should be:
- Introduce a topic (mention warnings early)
- Explain (focus/highlight, provide details)
- Conclude or summarize
If the layout of the paragraph becomes a factor, count the number of lines taken up by the body of text.
- Four line is ideal.
- Do not go beyond 6 lines.
Long paragraphs without breaks will tax the mind, and make the reader feel mentally fatigued.
A section must have a clear search-able sub-title.
A section must be complete and only discuss in detail one topic, do not overload the readers mind.
Never make use of something before introducing it and describing it. Do not shock, confuse or surprise the reader.
A title and section headings should capitalize the first word and all nouns. This is the style for most scientific publications.
Avoid the use of abbreviation of single words, it is just lazy and sloppy.
-
Do not use JS for JavaScript.
-
Do use MVC for "Model View Controller" once defined (multiple words).
Do not shorten a word to be lazy.
- Use "application", not "app".
Never make assumptions or think a step is simple, easy or obvious to be skipped over. This is a sign of a lazy writer. A technical writing should be thorough, complete, and stand on its own.
Do not tell the reader something is hard, difficult or complex. You plant false seed and set artificial limits in the reader's mind.
Avoid use of too many external references, when it is much easier to add text to explain things. This prevents the reader from context-switching between reading and having to jump to external references.
A colon should be used when providing a list of items, or sample code. A colon connects the preceding sentence.
Watch out for Apostrophes, for plurals, it follows after the letter 's' not before to indicate belonging.
- Colon: http://www.grammarbook.com/punctuation/colons.asp
- Punctuation: https://www.prismnet.com/~hcexres/textbook/gram1.html#colon
- Numbers: http://www.grammarbook.com/numbers/numbers.asp
Most modern editors have a spell checker or plugin, make use of it.
On Linux and MacOS use aspell, it is simple and interactive, the command is: aspell -c <file>