Islamic RevivalWriting Guide
Writing articles is an exercise in imaginitive empathy. We'd like to follow some rules and recommendations to keep some consistency to the prose on this site.
Principles
Respect readers' cognitive capacity (i.e. brain power)
When a user starts reading, they begin with a certain amount of limited brain power and when they run out, they stop learning.
- Cognitive capacity is depleted faster by complex sentences, having to learn more than one concept at a time, and abstract examples that don't directly relate to the content
- Cognitive capacity is depleted more slowly when we help them feel consistently smart, powerful, and curious. Breaking things down into digestible pieces and minding the flow of the article can help keep them in this state.
Always try to see from the user's perspective.
When we understand something thoroughly, it becomes obvious to us. This is called the curse of knowledge. In order to write good articles and documents, try to remember what you first needed to know when learning this concept. What jargon did you need to learn? What did you misunderstand? What took a long time to really grasp? It can be helpful to practice explaining the concept to people in person beforehand.
Describe the problem, concept or issue first, then the solution or detail.
Before showing the how, it's important to explain why it exists. Otherwise, users won't have the context to know if this information is important to them (is it a problem they experience?) or what prior knowledge/experience to connect it to.
Organization
Intro articles, essentials & summaries
Make readers feel smart, powerful, and curious, then maintain this state so that they maintain the motivation and cognitive capacity to keep learning more. These pages are meant to be read sequentially, so should generally be ordered from the highest to lowest power/effort ratio.
It should take no longer than 30 minutes to read, though shorter is better. The goal is to provide 20% of knowledge that will help readers handle 80% of scenarios. These can link to more advanced guides, remember that a smooth read is more important than being thorough in these kind of articles.
Advanced works and scholarly articles
While the intros and essentials helps people handle ~80% of the subject matters, subsequent articles help get users to 95% of that, plus more detailed information and references
Writing & Grammar
Style
- Headings should describe problems, issues or be a questions, not a solution
- When you assume knowledge, declare it at the beginning and link to resources for less common knowledge that you're expecting
- Introduce only one new concept at a time whenever possible (including both text and code examples). Even if many people are able to understand when you introduce more than one, there are also many who will become lost - and even those who don't become lost will have depleted more of their cognitive capacity.
- When deciding what to teach first, think of what knowledge will provide the best power/effort ratio. This helps learners feel smart, powerful, and curious, so their cognitive capacity will drain more slowly.
- Be emotionally relevant: Explanations and examples that relate to something people have experience with and care about will always be more effective.
- Always prefer simpler, plainer language over complex or jargony language
Grammar
- Avoid abbreviations in writing
- When referencing a directly following example, use a colon (
:) to end a sentence**, rather than a period (.). - Use the Oxford comma (e.g. "a, b, and c" instead of "a, b and c")
- Use sentence case for headings: There's research suggesting that sentence case (only first word of the heading starts with a capital) is superior to Title Case for legibility and also reduces the cognitive overhead for article writers, since they don't have to try to remember whether to capitalize words like "and", "with", and "about".
Iteration & Communication
- Excellence comes from iteration: first drafts are always bad, but writing them is a vital part of the process. It's extremely difficult to avoid the slow progression of Bad -> OK -> Good -> Great -> Inspiring -> Transcendent.
- Try not to get defensive when receiving feedback: our writing can be very personal to us, but if we get upset with the people who help us make it better, they will either stop giving feedback or start limiting the kind of feedback they give.
- Proof-read your own work before showing it to others: if you show someone work with a lot of spelling/grammar mistakes, you'll get feedback about spelling grammar/mistakes instead of more valuable notes about whether the writing is achieving your goals.