Short. Should not take more than 10 minutes to read. If the topic requires a longer tutorial, break it up into multiple.
Succinct. Verbose enough to cover the main concept, but absolutely no fluff or fillers. It’s okay to give extra attention to parts that are confusing.
To the point. Focus on the core concept, and don’t get carried away by the details.
Has diagrams, if they improve the explanation.
Intuitive and Easy to Understand. Don't use jargon that the reader will not understand without defining it first.
Avoid passive voice as much as you can. Passive voice complicates sentences unnecessarily. Don't write "The following result is generated by this code." Instead, simply write, "This code generates the following result."
Involve the reader. Write from their perspective. They should be able to feel the urge to go ahead and implement something once they are reading your tutorial. Use “you”, “your” etc. as much as you can.
Simplify your sentences. Try to cut out anything that shouldn’t be there.
Concrete, real-life examples. Not fictitious or made-up examples.
Be consistent with capitalizations. Technology names should be capitalized everywhere, so React and not react, Meteor not meteor. Be consistent with capitalizations within technology names too — use ReactJS everywhere, not Reactjs or reactjs etc.
Enclose code variables names in text in monospace. So if you define a variable called employee_list, it should always be monospaced throughout your writing.
Make sure the sentences are well formed, and the grammar is correct. Good writing is easier to read. A clean sentence requires hard work. It is not a work of accident.
Shorter sentences are better than longer ones. If need be, break a sentence into multiple to keep things simple.
Use conjunctions correctly. Conjunctions are words that connect two phrases together. Examples include but, yet, although, alternatively, additionally, etc. When used well, they inform the user of what is going to follow. If not, they can also throw the user off.
Don't link to external courses or blogs unnecessarily. Link to internal commonlounge tutorials/courses, or wikipedia/official documentation pages etc. only if necessary. Remember, links are a distraction in the learning process — they make the learner go away from the tutorial into a rabbit hole — leading to lower course completion rates. Our job is to make sure that they learn the most critical parts right here within the tutorial on Commonlounge.
Be as accurate and precise as you can be. If document.querySelectorAll(".circle") selects all elements with class circle, don’t write that it will select all divs with class circle. There's a difference — divs are a type of element, and the statement selects elements, not just divs. Attention to tiny details like these makes sure that the reader doesn’t get confused, and the past learning only gets reinforced.