Case study: making notes

How should you use N4L and SSTorytime? You can either use it as a programming framework, using the API, or you can create knowledge graphs by making notes with N4L. There are many advantages to using N4L: it's a very simple language that tries to bridge the gap between natural language and "logical" or at least "formal" knowledge graphs--so let's focus on that.

There is no right or wrong way to make notes, but the goal is to make a knowledge graph work successfully for you in expressing meaning.

• You write down things you want to remember (just informally at first).
• You look for pieces that you want to highlight as separate "characters" in your story.
• You try to join them up using "(arrows)".
• You define the arrows as one of four kinds of arrow: about cause-effect, containment, properties, or similarity.
• You keep going back to organize and improve them.

You don't have to get everything right the first time! The idea is to work on notes over and over again, to improve them.

Text, nodes, and names

When you write some text it can mean anything you like. If you want to related it to some other comment, you use arrows with "(..)". Parentheses that are not quoted are assumed to be arrows.

   Remark one ...  (arrow1)  another remark / thing / thought

If you want to add more arrow connections, use the "ditto" " symbol so you don't have to type the whole thing again:

   Remark one ...  (arrow1)  another remark / thing / thought

        "          (arrow2)  yet another remark ...

The nodes in a graph do not have to be "things". Don't think of notes as:

nouns (verb) noun   #   XXX No..

This will lead to artificial and inexpressive text. They might look "logical" or "computer-like", but this is not what knowledge management is about. Knowledge is for you and me--for humans! Any ordinary database can turn meaningful text into data fragments that don't speak to you, but with N4L you have the opportunity to write is more fluent language. Adding just a little bit of discipline will also make it easier to search later, and should make more sense to you when you are in a different frame of mind.

A simples mnemonic "etc", for writing notes, is to think of every statement as one of these three types: * Events - happenings * Things - physical objects * Concepts - ideas and virtual things

These help us to use the "right kind of" arrows for searching and reasoning later, because:

• Events "lead to" other events, they may contain things and express ideas.
• Things contain other things, but they don't contain events or ideas.
• Concepts express other concepts but they don't contain physical things. They can refer to events as examples.

The arrows in (parentheses) -- the four kinds

Each arrow is written in (parentheses). You can use a long or a short name. These arrows must be defined in the configuration files of SSTconfig/.

To begin with you can write down relations just as you might say them, but to make an effective knowledge graph, you need to reduce the number of arrows to a smallish but still expressive set. Each arrow must be one of four kinds/types, and this will help you to think about how to express relations.

You might struggle in the beginning to write your arrows in a good way. It takes a bit of practice. Here are some examples to help:

• Leadsto / affects / affected by / causes / caused by

    + causes   (cf)           - is caused by (cb)
    + creates   (cr)          - is created by (crtd)
    + predicts  (predict)     - is predicted by (predicted)
    + generates (gen)         - is generated by (genby)
        + enables  (enables)      - is enabled by (enabledby)
    + evolved into (evolved)  - evolved from (evolvedfrom)
    + determines (det)        - is determined by (detby)
        + founded (founded)       - was founded by (foundedby)
        + maintains (maintains)   - is maintained by (maintainedby)
        + runs or executes (runs) - is run or executed in (runsin)
        + run or execute before (runbefore) - run or execute after (runafter)
        + manages (mang)           - is managed by  (managedby)
        + authenticates (auth)     - is authenticated by (authby)
        + injects (inject)         - is injected by (injectby)
        + redirects (redir)        - is redirected by (redirby)
        + provisions (prov)        - is provisioned by (provisionedby)
        + constrains (constrain)    - is constrained by (constrainby)

• Contains or has part / is contained by or is part of

 + consists of (consists)  - is part of (pt)
 + uses word (useword)     - is a word used in (wordin)
 + contains (contain)      - belongs to (belong)
 + may contain (cancontain) - may be contained by (canbecontain)
 + should not contain / be excluded from (excludes) - shouldn't be contained in (excludedfrom) 

• Expresses an idea or property / has feature / is a feature of

 + discusses (disc) - is discussed in (isdisc)
 + obeys the rule (rule) - is a rule for (rule4)
 + has aspect (aspect) - is an aspect of (aspect of)
 + has key issue (key issue) - is a key issue of (is key)
 + generalizes (general) - is a special case of (special)
 + includes (includes) - is a kind of of (kind of)

 + should not (shouldnt)  - is not recommend about (notrecom)
 + has behaviour (behaves) - is a behaviour of (isbehaviour)

 + has resource/reference (resource) - is a resource for (isresource)
 + has feature (feat)        - is a feature of (isfeat)

• Is close to or similar to (mutual, has no direction)

 terminates together with (termwith)
 https connection with    (https)
 is not                   (not)
 don't confuse with       (confuse)
 similar to               (sim)

Kubernetes (short for) "K8s"
     "     (represents) a %container %orchestration system
     "     (foundedby) Google
     "     (maintainedby) CNCF
     "     (enables) %declarative %automation of containerized workloads

 pod  (represents) the smallest deployable computing unit in Kubernetes
  "   (named after) "pod of whales" or "pea pod"
  "   (contains) one or more %containers
  "   (runsin) a shared %execution context
  "   (managedby) %controllers

Labelling "sections" as lookup context

The "context" section tags are terms you expect to use to look up what you are making notes on. Naively, they are like section headers in a book. More deeply, they are like index words that you will be able to filter searches with.

 :: core concepts, tags, thoughts you have, index terms  ::

Adding annotations to text

We can use annotations like "%" and ">" to add sub-references to a string of text. There is no need to label too much, but sometimes you might want to explicitly connect a sentence to one of its subjects.

You can use quotes around parts of a sentence to collect words with spaces or special characters.

 
Kubernetes (short for) "K8s"
           (represents) a %container %orchestration system
           (foundedby) %Google
           (maintainedby) %CNCF
           (enables) %declarative %automation of containerized workloads

There is no purpose to writing:

 %Mark (loves) %Lynn

because Mark and Lynn are already defined as text just by writing them independently. But you might want to write:

%Mark sometimes visits the old pub where %Lynn used to work (describes) Some dating habits

Hints and tips

You can make text readable by adding more natural forms, and finding a balance between abbreviation and natural language:

   # instead of #  container (managedby) containerd

   container(s) (managed) the %containerd process

   # instead of # kubectl (usedto) interact with kubernetes via CLI

   kubectl (usefor) user interaction with kubernetes via CLI

Avoid using our over-used verbs like "is a". These don't express anything useful. You can say something like "is an example of" or "is a type of" to add a meaningful description of the role.

  # instead of # "One-container-per-pod" (is) the most common usage pattern

  "One-container-per-pod" (example) usage pattern  // make this an example

If you are trying to describe complicated behaviours

 
 init containers  (runs) during pod startup
        "         (runbefore) main application containers
        "         (usefor) setup tasks like config init or dependency checks

sidecar container (runswith) main application container
         "        (shares) the %pod’s network and storage context
         "        (usefor) %logging, %proxying, %service mesh, and other supportive tasks
         "        (enables) separation of concerns
         "        (termwith) the main container

If an idea is too hard to write as relations straight away, just write it as a sentence, and you can annotate it. It's more important that the knowledge is understandable than logically perfect.

'Kubernetes uses a >"hub-and-spoke API pattern". All API usage terminates at the API server.'

Thinking in verbs tends to make us write this:

%service account (injects)   %bearer token and %root certificate into pods
%kube-proxy      (redirects) service IPs to %API server HTTPS endpoints
service account  (injects)   %bearer token and %root certificate into pods
kube-proxy       (redirects) service IPs to %API server HTTPS endpoints

We should ask ourselves, will we ever reuse these arrows (injects)? Would it be simpler just to write the sentence without the arrows?

 reconciliation (represents) %abductive reasoning
       "        (observes) reality
       "        (infers) steps needed to achieve promised state

reconciliation (means) Observing the %"actual state" and compares to the %"desired state". It infers the steps needed to achieve promised state. (note) This is a kind of %abductive reasoning.