Writing articles

Write an article with the mindset that tomorrow:

  • you are in a hurry (hence make maintaining it easy & fast)
  • you forgot everything (hence make reading it easy & fast)

Apply the principles more strictly when dealing with a larger corpus.
Continuously iterate over existing articles.

Do not repeat yourself (DRY)

Have a single article for each concept, and link to it when needed.

Fully explain a single topic.
Split / restructure articles if not easily possible.

Keep it simple, stupid (KISS)

Choose the simplest, shortest, stupidest way to express something.

Use positive formulation.
Remove everything that is not strictly necessary.

Separation of Concerns (SoC)

Separate different levels of details (overview, in-depth) and different topics (know-how, experience, advice).

Create an overview article and link to articles with details.
Separate know-how (what is known to be true) from experiences (what happened) from advice (how to do it next time).