Differences

This shows you the differences between two versions of the page.

--- writing-style [May 14, 2026 at 11:38] – external edit 127.0.0.1
+++ writing-style [May 25, 2026 at 20:24] (current) – removed Ivan Janevski
@@ Line 1: / Line 1: @@
-# Writing style
-**Writing style** is about you approaches writing a document for other people to read. This document can be a blog post, a piece of documentation, or code. This particular page talks about how I approach writing this website. It's going to evolve over time.
-The trouble with writing is that thoughts are non-linear and ideas come and go. Writing is inherently a serialization of thoughts.
-## Patterns
-*Target the second person*. Don't use passive voice. Be direct. Write as if your friend or a colleague sitting right next to you, and you're trying to explain a topic to them.
-*Be clear*. Don't overcomplicate. Don't overstate. Try to make your document useful instead of confusing.
-## Anti-patterns
-*It's easy to see...* Is it *really* easy to see? Easy for whom? Tell the reader why it's easy to see. You don't have to go step-by-step, but you should give a hint to the reader how to arrive to the same conclusion.
-*Acronyms*. Don't use them. Definitely don't define your own acronyms. An exception is when an acronym is so common it's understood by everybody (OS, API, HTML, ...)
-*Profanity*. Don't use profanity at all. It's unprofessional.
-*Don't embed parenthesis*. Don't embed parenthesis (i.e. like this) or do something (e.g. like this). Use two sentences instead. Branching mid-sentence is bad practice.
-## Target audience
-Anybody who already uses GNU/Linux and is interested in learning embedded engineering or mathematics.
-## Hazards
- - Analysis paralisis
- - Over-reliance on structure
- - Writing and rewriting over and over again
- - Writer's block
- - Unfinished articles
-## Considerations
- - Write in a way to give a practical guide rather than mimic documentation
-## Principles
-Axiom of choice: I give myself freedom to write whatever I want. Any style is a suggestion rather than rule. Imposition of style comes after having written something. There is no structure without  elements.
-Every section needs to have a clearly defined scope. It shouldn't "leak" in a sense that there are things that could've been said.
-Every section should be written as a draft first. Revisions come later. Draft comes from my stream of consciousness, and then we'll make it into a finished product later.
-Every section needs to follow a certain format. If it's about code, it should only contain code. If it's prose, it should only contain prose. If it's about lists, it should only contain lists. There needs to be.
-A section needs to be thought of as a unit with a context stream. Context
-Cohesion and structure is important, but we need elements first. We need sentences and paragraphs first -- then we can fit them into a wider structure.
-Always prefer prose over lists or tables. Do not embed lists and tables within prose. Put them at the end or a separate section. Treat prose as atomic.
-Always prefer similarity and repetition when you write sentences. Similarity invokes symmetry, which yields structure more easily than
-Don't over explain. Given a reader's background knowledge $E_n$, where $n$ is the reader's knowledge level, consider $\Delta E$ such that the reader leaves with knowledge $E_{n+1} = E_n + \Delta E$. Do not try to rebuild $E_n$, focus only on writing $\Delta E$. The reader can decide for themselves whether their level $n$ is sufficient or not.
-Always prefer active over passive. Use instructive language, like "you need to...". Always consider what the goal is and lay down instructions towards that goal. If goal is $G_n$, lay down the steps $k = 1, 2, \dots, n$
-Always treat the first sentence in the paragraph as more important than second or third sentences. The first sentence should lead with an idea. The second, third, and fourth sentence in a paragraph should
-## List of principles
- - The first sentence should start with the word in the title bolded.
-## Anti-patterns
-Avoid embedding (e.g.) and (i.e.) within a sentence. This makes the sentence difficult to follow. Rather, split the sentence in multiple simpler sentences.
-Use instructive language but avoid using the generic "you". Don't say "you need to install X in order to ..." -- instead say "install X in order to...".
-Use singular when examining properties. Don't say "Incrementing semaphores will..." -- rather, use the singular "semaphore".