# representational reasoning and simplicity keywords, phrases, and descriptions related to making systems easier to think about and easier to write down, by simplifying both the way information is expressed and the way ideas are organized. # external form * [documentation templates](simplicity/documentation.html) * [standards and units](simplicity/standards-and-units.html) ## general * ascii only * lowercase * only essential parts * avoid redundancy * avoid excess abstraction ## writing style * one idea per sentence * only subject-verb-object sentences * no nested clauses * avoid synonyms and idioms * prefer declaratives or process actives * avoid numbering in headings or lists, as it makes modification difficult # conceptual organization * [software simplicity](simplicity/programming.html) ## representation exploration simply collect relevant words/keywords/vocabulary. build clusters of related concepts. identify transferable knowledge. structure notes as conceptual clusters with cleverly chosen category names. labelling introduces discrete boundaries in the problem space. discretization permits combinatorial search, recombination, inference, and comparison. the manipulation of symbols, rather than undifferentiated experience, enables the detection of sameness, adjacency, and absence. it also supports compression of reasoning. ## primary vectorization * create tuples of variables to map conceptual space. * identify orthogonal primary variables {v₁, …, vₙ} spanning the conceptual space. * for each variable, define orthogonal subvariables to refine coverage. * incomplete vectors reveal missing dimensions; formulate questions that resolve them. ## minimum-questions protocol find the smallest high-leverage fact set that yields broad understanding. use a "20-questions" framing: each question carves the search space, reduces ambiguity, and links categories. ## bottom-up accretive composition * extend only by increments that persist in the final system * additions extend the shape already present, not correct or replace it * represent unbuilt regions by identity or no-op boundaries, never provisional stand-ins * consolidate only when multiple increments contain the same pattern and replacing those duplicates with a single shared component reduces overall complexity * "even if it is not perfect, prepare it to become so" ## triplet completion computation viewed as a triplet: (input process output). triplet reasoning treats each unit as a relation in which any two elements determine the third: ~~~ (input, transformation) -> output (output, transformation) -> input (input, output) -> transformation ~~~ this yields: * representation: every component is defined by input, transformation, output * inference: if two are known, derive the third * diagnosis: if the third cannot be derived, the design is underspecified or discards information therefore: * the triplet pattern models functional evaluation directly * completeness holds when evaluation is pure and referentially transparent * failure of triplet closure indicates side effects, hidden state, or partial observability in programming language design, the triplet describes the semantic core: ~~~ (expression, environment) -> value (value, environment) -> expression (only if representation is retained) ~~~ thus the same principle: * where evaluation is reversible, structure is transparent * where evaluation is not reversible, information was discarded practical use: * when integrating components, chain triplets by matching outputs to inputs * when debugging or extending, reconstruct the missing element from the two available * when this reconstruction fails, refine the representation until closure is restored ## duplet mapping computation viewed as a duplet: (input output). a duplet omits the internal process. only two questions remain: * which inputs influence each output * where each resulting value appears in the output structure this yields a minimal observable model. ``` input -> output ``` ### argument mapping duplet reasoning focuses on what flows and where it ends up, independent of how it is produced. it can be notated as nested sets of value identifiers to show what is being mapped. for example: `a (b (c d)) -> a (e f)`, where parentheses mark collections. to avoid duplication of definitions at other places, it usually makes sense to describe structures somewhere else, given them a name, and then have a flat list of input and output values. for example: `a g -> a h`, where g and h are described separately. a mapping of input to output arguments is specified by two orthogonal choices: * selection: for each output position, choose zero, one, or many input positions * placement: assign the produced value to its output position four primitives span all cases: * omit: no selection, no value * include: select one input, identity * transform: select one or more inputs, rewrite * restructure: place result at any output position or depth this will show transformed input and output, and values that are merely passed on unmodified. ## rationale optimization * evaluate options against objectives, constraints, and trade-offs. * document rationale and mark chosen paths ## algorithmic identity encoding about the compact description of algorithms. ### what it means to encode identity an encoding of algorithmic identity provides a language-independent description of a method. sufficient to distinguish algorithmic families such as quicksort versus mergesort. it abstracts from machine details and retains only defining structure, recurrence, or partitioning. good encodings are judged by: * clarity of essential steps * omission of incidental implementation detail ### variable elements and abstraction * represent domains abstractly when only their properties matter. * a concrete representation is needed only if the algorithm depends on those specifics. * example: quicksort requires a total order but not the bit width of elements. * if overflow or rounding affects correctness, drop the abstraction and specify concretely. * the principle is to keep abstraction at the level of properties essential to identity, refining only when representation influences correctness. ### semantic styles * operational semantics: state transitions, imperative pseudocode, abstract state machines * denotational semantics: input-output mappings, recurrences, set-theoretic relations * algebraic semantics: equations and laws, algebraic specifications, horn clauses ### refinement principle * begin from a high-level specification that defines identity, e.g. "permutation and sortedness". * refine stepwise into a partition-based recurrence, then pseudocode, then machine code. * each refinement preserves correctness; the refined form implies the original. ### encodings of identity * natural language description * functions * imperative pseudocode * mathematical recurrence equations * horn clauses / logic programming * algebraic specifications (equational logic) * set-theoretic relations (input/output and invariants) * category-theoretic combinators (folds, catamorphisms) * abstract state machines * type-theoretic or refinement-type specifications * flowcharts or control-flow graphs * state-machine morphisms (mealy or moore; specific reactive subclass) ## mathematics * mathematical notation using only ascii and function notation or english descriptions * replace non-ascii glyphs, non-linear spatial layout with a linear ascii syntax and semantics ## inquiry questions that can bring forth fundamental properties. * "what is x always" * "are there shared fundamentals between these two designs that could improve either" * "does this application or usage expose flaws in the orthogonality of its parts" * "what minimal set of primitives generates the observed variety"