1. Asciidoc

Asciidoc should be formatted according to Asciidoctor’s Recommended Practices. The notable thing that’s counter-intuitive is "One Sentence Per Line".

2. Updating the Template

Be very careful about waving away difficult setup for modules behind "oh, but the template generator can do that!".

  • This kind of change makes it difficult to roll out improvements to existing users

  • Users should always be looking at low-clutter files in order to allow them to maximize focus on their project, not Edge

Clojure is an extremely dynamic language, and it’s likely that you can find a solution which involves dynamic loading.

3. Updating modules

Be careful around the really common paths for users (lib.app.dev, lib.app.prod). I don’t think Edge needs perfect stability, but close enough should happen.

When updating things think really hard about the impact on existing programs. Conditional & deferred resolutions of dependencies may be helpful for these cases.

It’s okay to offer new features, but degraded unless the user takes action.

4. Writing Documentation

A great reference on how documentation should be written is https://jacobian.org/tags/great-documentation/. See Django’s for an example.

5. Design Principles

Design principles to keep in mind when working on things.

  • Developers want to focus on their projects not Edge, component systems are just incidental complexity

  • Modules allow people to reduce the program scope stored in their head at once

  • Modules allow updating code for people without merge conflicts

  • Simple and Easy is a careful balance, but Edge aims to be easy