IBIS Format - SMotaal/specs GitHub Wiki

Information-based Issue System

The Information-Based Issue System (IBIS) is an approach for asynchronously developing solutions to issues, and retaining institutional knowledge about those resolutions so that they can evolve over time. The format uses an outline, with initial characters to indicate whether a given paragraph is an issue, a position on an issue, an argument for or against a position, etc.

Semantic Symbols

Symbol Meaning
? An issue to be considered
?! A resolved issue
?~ A tentatively resolved issue or an issue that is still open but that has a fallback position
: A position (on an issue). Multiple positions on the same issue are not necessarily mutually exclusive
:+ An accepted position
:- A rejected position
:~+ A position that is tentatively accepted or that is a fallback position for an issue
+ A pro: an argument in favour of a position
- A con: an argument against a position
! A to-do for an element
. A comment for an element

Notes

  1. Issues can be nested. This is typically used for discussing some portion of the outer issue separately. Positions for sub-issues should be nested under them.
  2. Positions can be nested. The sub-position represents a refinement that assumes the outer position is accepted. Arguments for the sub-position should be nested under it.
  3. Arguments for a position are always positive or negative with respect to their containing issue. Thus, a positive argument nested underneath a negative argument is typically a mitigation of the negative argument (e.g., here's why that negative argument isn't so bad).
  4. The ?~ and :~+ notations are primarily to support establishing fallbacks. Fallback solutions to design issues enable agreement on a minimum bar, while leaving an issue open for further discussion. Often, an initial fallback will be the status quo, and the design discussion is to find and consider better alternatives. Note that it will remain easier to achieve consensus on fallback positions if the fact that a position is a fallback does not preclude consideration of other options.
  5. Issue (?) β€” Describe the issue in a complete sentence. The description should be phrased to support multiple overlapping positions rather than e.g., non-overlapping answers such as β€œyes” and β€œno”. Thus, β€œ? what tools should we provide for enterprise developers?” rather than β€œ? should we support VSCode?”
  6. Position (:) β€” Describe a potential solution, partial solution, or other statement to be considered to address the issue. Description should be complete sentences. Positions can overlap or conflict. They can be refined with further sub-positions underneath, and so need not capture all the ramifications. E.g., : support VSCode could have subpositions : provide a VSCode add-on and : write config doc for VSCode
  7. Issues can really only be resolved if some position has been accepted. Not all positions need to be accept/rejected however.
  8. For editors, it may be important to suppress auto-bulleting when you start a line with - or ..