Essays: A Manifesto

Originally drafted October 27, 2021 and last tended May 16, 2023 by Matt McElwee.
(See Revision History).

One of the biggest challenges of building a personal website, especially one which you wish to mean something, is that you run the risk of adhering to the static methods of publishing post-Gutenberg.

  1. Notes should be tended to like a digital garden. Like good software, documentation should be a constant effort of iteration. The challenge is that we often treat blog posts as something that is shipped and then complete. Instead, we should think of the first "published" draft as a seedling or starter plant which will grow over time. This plant must be tended, watered, fertilized, and weeds plucked out from around it for it to flower.
  2. Notes should be evergreen. This means that they are developed over time, they evolve and are accumulated upon. Andy Matuschak gives a series of principles which help define what makes for a good evergreen note/doc:
    1. Evergreen notes should be atomic
    2. Evergreen notes should be concept-oriented
    3. Evergreen notes should be densely linked
    4. Evergreen notes should have an organization which emerges organically, rather than one that is based on information hierarchy
  3. Opt for imperfect notes that are merged over a note that isn’t posted but may be perfect when it eventually is. GitLab’s value of iteration sets this idea up well.
  4. Stub notes are a useful means of favoring densely-linked notes. This note needn't be written beyond a title. This helps to create a network of ideas and build on those ideas iteratively.
  5. Note and essay titles should act as an abstraction for the text itself and should be complete phrases. This allows unfinished stubs to demonstrate value and allows for an iterative network of knowledge to grow.
  6. Since most notes will begin their lives as merely a stub with a title, an expression of the level of certainty I have should be included. In addition, I am to speak to completeness, accuracy, and level of effort given to the current state of the note.
  7. I aim to abide by the digital gardening terms of service.
  8. When a piece of documentation requires some previous technical or domain knowledge, that information should be included with the other “meta-knowledge” information.
  9. All notes and essays, as far as they may, ought to abide both by this manifesto and by my stated values of writing.