Specification as art

Writing good specification is an art. Difficult art. It's about asking the proper questions (sometimes to oneself), and writing the Complete Answers down, properly. Unambiguosly. May take years to master it, working on both sides of the fence.

But don't despair.

Note: in math expressions, parentheses () denote higher precedence of what is inside them than outside , recursively. So in a+(b+(c+d)), c+d has highest precedence, then b+.., then a+.. and Highest precedence happens first. In human language, parentheses means some grouping.

---

---

The anecdote goes:

Programmer's wife tells him to "go buy bread, and, if there are eggs, buy 10".
So he returns home with 10 breads..

And this is because (note where the parentheses are):
    - plain human interpretation: go buy bread, and also (if there are eggs, buy 10 [eggs] )
    - math/programming-like interpretation: go buy bread, but (if there are eggs ), buy 10 [breads]

How to make it better? depends what exact outcome/s one wants.. (btw "buy" implies "(if available)" anyway, so..)
    - "go buy bread and also buy 10 eggs"
    yields: 1 bread + 10 eggs if both exist, 1 bread if no eggs, 10 eggs if no bread, or nothing
    - "go buy bread, and only if it is available, also buy 10 eggs"
    yields: 1 bread + 10 eggs if both exist, 1 bread if no eggs, or nothing
    - ...

---

---

Another example:

2+2*2 means:
    - 2+(2*2) -- with operator precedence within whole expression (multiplication is higher, hence before sum)
    - (2+2)*2 -- with first-come precedence (plain calculators) (sum before multiplication)

---

---

There are many-many non-plain-human languages, some with weird syntaxes, each optimized for particular goal, mostly not for readability/ common-understandability..

Most procedural programming languages may have this:

    if x>1 then x=5

or simpler

    if x>1 x=5

but some also have this (of same meaning):

    x=5 if x>1

and allow things like:

    if x>1 x=5 if x<3

which gets tricky/ambigious, it has multiple possible meanings, without obvious choice:
    - p1: [ if x>1 x=5 ] if x<3
    - p2: if x>1 [ x=5 if x<3 ]
    - and they both seems to be same as:
    p3: if (x>1 AND x<3) then x=5

except that the order in which comparisons are computed, is not the same - p2/p3 compute x<1 before x<3 , p1 is reverse; Neither of these would matter unless those computations have side effects and may influence each other.. Anyway, actual precedence will be specified in language's documentation, but it's not obvious.

Devil is in the details... and nature has amazingly deep level of detail, and any model is purposefuly only scratching the surface, and better avoid including more things than assumed/expected.

---

---

But one of the most obvious discrepancy between natural language meaning and math meaning, is:
    - human-AND usualy means AND-ALSO i.e. additive, one next to other,both THINGS existing at same time, i.e. math-OR/union,
    - math-AND means both CONDITIONS at same time, one-on-top-of-another
    - human-OR means math-ONE-OF/exclusion
    - math-OR means union, additive

In most cases this may not be a problem, but better be aware.

Example: box contains some red apples mixed with some green apples

In natural language:
    a) what apples are in the box? red AND green
    b) box has red AND green apples

which is math-incorrect, there is no color that is both red AND green , the color is EITHER red OR green

The reason b) comes as incorrect is because it is SHORTER version of more correct 'box has red apples AND box has green apples', or "box has apples that are either red or green". Similarly, "i get a red OR green apple" is shorter of "i get EITHER red apple OR green apple" or even "EITHER i get red apple, OR i get green apple"

in math:
    - (box has red-apples) AND (box has green-apples)
    - box has (red-apples OR green-apples)
    - box has union of ( red-apples , green-apples )
    - box has apples of color (red OR green)
    - what color one apple may have: red OR green i.e. union( red, green)

or, in the above "buy bread AND eggs", someone may interpret it purely math, and bring bread AND eggs if they both exist, or nothing if either is missing..

---

---

So... in specs:

    ** if something can be misinterpreted, it will be misinterpreted. **

Try to avoid any such possibility. Do not require guessing, avoid contradictions.
Note that implied things call for guessing, which may also yield contradictions, and repeated things also allow for (future) contradictions. And it is very easy to underspecify and overspecify, even at same time.

Specs are about conveying meaning. And nothing else (variety, beauty, attitude, mood, ..). Any word (taken out of context), brings it's own context - better keep those contexts to possible minimum. Make them explicit, minimize implied contexts - or anyone may imagine different context/meaning. So treat words like keywords/terms - it is not beautiful literature, it ought to be boringly consistent and detailed but succint. Eh, Which does not mean it has to be ugly or unreadable.

one thing = one name = one meaning:
    1. one thing has only one name - tautology is mandatory. Naming something X, always name it X, do not also name it Y. "i have cup (of water)" .. and then always use "cup". Don't also use glass, mug, tumbler or whatever synonyms - they have lots of other meanings.
    2. one name has only one thing - never name different things same.

Similarly, do not repeat combination of words - phrases, sentences, whatever, esp. adding-or-removing characteristics. All similar (but not same) instances automaticaly become ambigious/contradictory. Say, postulating "i have red apples", then few lines further but still within same thought, "i have ripe apples".. , or "i have apples", turns one meaning into possible 3 or more.

As of what to write about.. there are 2 styles, one is about HOW, prescription-like, specifying all materials and processes and leaving no room for invention, and the other is about WHAT, outcome-expecting, with as little guidance as needed. Mostly the second, WHAT, is to be used around software, except when some business-process or practice has to be followed exactly. Also, while developing, an intermediate working specification may be made, and it may evolve slowly, while finding and fixing the unknowns, from outcome-expecting WHAT into prescription-like HOW, becoming more and more rigid. And one more thing... in most cases it is very useful to also know the WHY of the things required/ described. Even for the author, looking at it later.

This leads into the notion of Use-Cases (mix of empirical and theory). Think of usecases as some hierarchy of reason-consequence paths (i need this, which needs these, which ... further into it). So one use case is describing some WHAT, its parent case (the reason it exists), describes the WHY of it, and its children (the consequences), describe the HOW. These may be labelled: WHAT is sea-level, WHY is sky-level, HOW is sea-bottom-level. Try to only describe the current WHAT/sea-level, and avoid mentioning other levels, or only mention the direct neighbours, i.e. parent/children. This seems obvious but is surprisingly difficult to follow, because human mind is always optimizing and solving for the how. Hence, answering the wrong question:

https://xyproblem.info/

Further, there is whole Requirements Engineering / Management discipline, which tries to apply traceability and trackability and validation and static-analysis etc, onto the set of specification-requirements changes themselves. Allowing answering questions like "what functionalities would be impacted if X is done/ not-done/ changed", or what requirements contradict certain new requirement/change, or why this function exists at all, etc. Such things are highly needed (still, rarely done) in domains where the result is not much fixable after the fact, e.g. hardware, but not only.

At the end.. one old paragraph that grew into all this:

requirements, analysis, specification... are the most important link that can not be missing. Software is made of decisions. And main tools in software making are... the right questions. Whatever they are - the 3 levels in a use-case (why-what-how), or the kind of programming - procedural (how), functional (what), reason-goal (why), object-oriented (who) ... or the simple doubting "Whether it should".

---

---

    I keep six honest serving-men
    (They taught me all I knew);
    Their names are What and Why and When
    And How and Where and Who.

Rudyard Kipling - http://en.svilendobrev.com/1/6men.html
(probably there is poetical translation in your native language, find/read it, might give yet another interpretation)

and yes, One should be able to be (selectively) stupid:
https://journals.biologists.com/jcs/article/121/11/1771/30038/The-importance-of-stupidity-in-scientific-research

have fun
nov.2021