notes-organization-designConcepts

Here's some concepts/ideas i use when designing things:

things i make lists of:

• competitive advantages and disadvantages (whys): what approach does the thing i'm designing take that is different from its competitors, and what are the pros and cons (tradeoffs) of this approach? That is, if you are designing a thing called X, then if X had been built already and you were describing it to a potential user, in your presentation you might have a slide "Why X?". Often there is a
• design priorities: closely related to whys. For example, if you are designing a programming language, 'readability' might be a priority. I use what i call the 'prime priorities' approach; what are your top 3 priorities when making design choices? What are your top 5? What are your top 7? What are your top 11?
• anti-priorities: things that some competitors prioritize that you don't. For example, a programming language anti-priority might be "throughput performance" or even "performance".
• use cases: what sorts of things can a user do with the thing you are designing? At the low-level, this is a list of tasks that users need to complete; at an overview level, this is sort of, what is your user market segment? For example, within programming languages we talk about 'systems languages' and 'scripting languages'
• questions: what are important open questions that you need to think about?
• 'should have a way to's: a low-level goal that a user might have for the thing being designed. For example, for organizational systems, 'need a way to keep track of stuff to say to a collaborator next time you talk to them about this project'. This is a form of story.
• perspectives/approaches: a way of grouping together/categorizing stories along with a way to solve these categories with features. For example, in organizational systems, a perspective is to think separately about features for dealing with near-term, tracked tasks vs dealing with indefinite/low-urgency tasks, and an approach is for indefinite/low-urgency tasks to focus more on filtering them via fine-grained importances. For example, in programming language design, a perspective might be 'resource management', which might lead to an approach of 'high-level safe resource management' with features like Pythonic 'with'/Lisp unwind-protect but also Rust's approach to RAII.
• inspirations: competitors to learn from. For example, if you are designing a programming language that you think of as "the best parts of Python and Haskell", then Python and Haskell are inspirations.
• toreads: stuff to maybe read someday, organized into topics
• (core) data structures
• UI screens/modes and flows between them
• ui views / filters / queries
• todo list(s) for design, project todo and status
• documentation of design decisions and their motivation (perhaps presented as a list of dated memos/log entries, or perhaps presented in FAQ form). I don't try to keep this up-to-date or to document every major decision; i just go back and write stuff here when i feel like it. Despite calling these 'decisions', just because a choice is memorialized here doesn't mean it is not very tentative and subject to change -- the point is just to help me remember why i chose something, not to create a list of firmly 'decided' choices.
• introduction to the project (free text)
• an old/ folder with an archive of out-of-date files
• in the old/ folder, files with either the word Done appended and/or a date in the format YYmmdd appended to the end of the filename (before the .txt) containing obsolete versions of files and/or obsolete text from elsewhere in the project (such as notes that i've either acted upon or decided to delete)
• 'need a solution for's: troublesome user situations that i'm not quiet sure how to help with
• situations/solutions: specific situations that a user might find themself in that suggest a design need that we have an approach to solving -- when we choose a (partially) solution for a 'need a solution for', then the 'need a solution for' turns into a situation
• stuff to think about
• features
• feature summary list

design document plaintext files:

• all files are in a folder, and start with an abbreviated name of the project (so that it's easy to search for them to open from my text editor)
• file names are in lower camel case format (eg lowerCamelCase)
• file names talk about the topic or part of the thing whose design they describe; for example, "ootTypeSystem.txt" is about the programming language Oot's type system. This file describes the current draft design for this topic or part.
• for each topic, there may also be a 'thoughts' file with a name like "ootTypeSystemThoughts.txt". These are tentative design decisions and other thoughts that are important enough that i don't want them to get lost.
• for each topic, there may also be a series of 'notes' files with a name like "ootTypeSystemNotes2.txt". These contain everything else that i write down about that topic. I try to keep each notes file to about 1000 lines; when it gets much larger than that, i create a new file in the same series.
• there is also a 'top-level' draft design file (with a name like oot.txt), and a top-level thoughts file (eg ootThoughts.txt), and a series of top-level notes files (eg ootNotes21.txt)
• there may also be other files describing design stuff other than topics (eg whyOot.txt to describe whys; ootQuestions.txt to describe design questions) -- these can also have thoughts or notes series associated files, but typically don't
• the draft design files are written as structured documents (with headings, subheadings, etc in some lightweight markup language). The thoughts and notes files are mostly just a bunch of sections separated by '---'. On the next line below '---' i sometimes put some 'tags' to allow me to easily search for topics with the files.
• all files use my 'personal notes files' typographic conventions, which means that i do things like write 'i' in lower case, and i just quickly copy/paste in stuff from web pages that other people wrote without properly quoting and citing those quotations, etc (it's usually clear to myself which things other people wrote though, for example if i copy/paste in stuff from a web forum the presence of a weird username or date at the top of a comment is a dead giveaway that this is something that was copy/pasted; but it might not be easy for someone else, or even for me, to find the original source just from that, especially now that Google doesn't index so much stuff anymore), i try to use only ASCII, i feel free to edit typography in stuff i copy in even if quoted (eg i might concatenate two paragraphs into one long paragraph). These files only need to be understandable by me, not by anyone else, although i usually make them public anyways.

methodological concepts and principals:

• avoid design by committee, for two reasons:
• you need to make harsh simplifying decisions rather than compromises
• design thinking has to consider a large number of aspects of the problem at once which constrain each other; this is best done inside one person's brain or at most in a discussion between 3 people
• "diverge to take in new ideas, converge to rationalize and make consistent" -- Kurt Laitner
• design space: there are a number of choices to be made; some of these choices constrain others; the space of permitted assignments to these variables is called 'design space' (note that in reality these tend to be soft constraints rather than hard; that is, it's not so much that choosing A=1 and B=2 is illegal, it's rather that the combination of A=1 and B=2 has some disadvantages, but may still be justifiable in some situations
• i have a friend who prefers not to interrupt project conversations with note taking because e says "i remember good ideas". Well, in contrast, i don't remember even good ideas; so if i have a thought that i want to remember, i try to write it down.