Follow up to the last note about the hint documents. Generally speaking I should clearly organize documents using a category system. The 'ideas' folder is such an attempt, but maybe some large categories in the title would help:

• Brainstorming or Idea or Concept: live log about a concept or idea, unstructured.
• Research: structured with version, or unstructured with live log. Explores one singular topic. Similar to brainstorming but more focused on a single topic.
• The separation between research and brainstorming is fuzzy. Brainstorming kind of implies the document is unfocused and quite exploratory. Research kind of implies I already know more or less what I want to talk about.
• I don't like the word "Brainstorming." In fact I don't like any of these qualifiers here.
• Design doc: structured, not a live log. Use versions to capture evolution. Describes one specific project, in a singular version. Discussions go in another document (concept one).
• Implementation: companion details about a single design doc version. Unstructured, live log. If one topic gets too large, extract it into a research document.
• Platform or Overview: large description about a given system that might encompass several projects. Structured, with versions. Ongoing discussions go into a live research or brainstorming document, the overview document captures the summary of a potential state.

Applying this to the hint thing:

• "Platform hint" becomes Brainstorming on the ikaria platform.
• Overview: Ikaria v1
• Overview: Hint language v1. --> design doc v1.
• Research: feedback on clojure.
• Research: immutable data types for closures.
• Idea: Cloud Bus --> Design doc v1
• Brainstorming: Robot game. --> Design doc v1 --> various design doc links to subprojects.

Also go back to older documents and rename them as clearly obsolete.

[...]

I think I'll settle for [Idea] and [Research] for now.

Part of the goal is to have a more systematic approach. Most of my documents are merely exploring an idea for an app or a library and are often expressed as a list of "specifications" that combine both desired features and potential implementations. One goal would be to have a more structured and formal approach where there's first a discussion document that explores possible variations and then settle down on one particular set of features & implementation.

Phase 1: A project description starts with an [Idea] document.

• Often I just stop there or have various iterations on the idea. That can go into the same document.
• If at some point I decide I'm taking a radically new direction, I should make a new version (so Project Foo v1 [Idea] ⇒ Project Foo v2 [Idea].) Make sure to link to the previous one for reference.
• Many times a document would describe an idea along with a potential "specification" overview. The pattern would be to add "Spec" to the doc title, but it's not a category by itself, it's still an idea unless it's formally rewritten as a design doc. That's because such documents are generally live documents where the proposed spec is part of the exploration, and not necessarily final.

Phase 2: If the project starts to get serious enough, try to stabilize one version of it.

• This becomes an [Overview] document or a [Design Doc] document.
• These documents should describe the project fixed at a particular implementation. If it turns out to not be satisfactory, amend the [Idea] document with an on-going discussion and continue stabilizing the idea.
• Only a minority on medium-to-long term "serious" projects would get that treatment.