IBIS

IBIS

Issue-based Information 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.

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 favor 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 “.”.

Example

1. ? How should we test our software?
   2. : use a test runner of some form
   3. : build a QA department
   4. :~ use tape
   1. + it's what we currently use
   2. + it's very simple
   3. + we almost have a SES version of it
   4. + it works in numerous environments
      1. - it's not very expressive
   5. - it doesn't have code coverage
   6. : use Jest
      1. + lots of people like it
      2. - guess-my-syntax DSL for expressing assertions
         1. + you can separate the assertion choice from the framework
      3. + can do integration and unit tests very well
         1. !jf can it do them better than tape?
      4. + It supports parallel test execution
      5. + It introduces new intrinsics for every file
         1. . Its real value is the test runner
   7. : roll our own test runner
      1. : make them importable ESM
         1. . then we can run them in XS
         2. + could be simpler than tape
         3. + could be compatible with the Jest runner
         4. - requires implementation and maintenance
   8. : for whichever runner we choose, create in-SES and in-Jessie versions to simplify tests
   9. :+ use test262
      1. + required for JS standards testing
         1. - clunky for other uses
   10. . there are actually three separate choices: test-runner, test environment, and assertion library
   11. ? What assertion library should we use?
   12. ? What test runner should we use?
   13. ? what test environments should we support
       1. : SES
       2. : Jessie
       3. : NodeJS
       4. : in-browser
       5. : XS