RFC W0192: Use of +, ~, @; clarifying extend-the-end

This post is a request for comments. I am actively seeking your feedback. This feedback will influence the development of Johnny.Decimal. Feedback closes at the end of 2026-07-30. Details are at the end.

I put this post together quickly as a result of this time constraint. (Its decisions are holding up the recording of additional Task & Project Management (T&PM) episodes.) So it's a bit rough around the edges: I'll write up something more formal when feedback is in.

One of my goals has always been for the Johnny.Decimal system to be semi-formal. By which I mean that there are clear – almost mathematical – rules that define it.

This has many benefits. Clarity, obviously. Consistency. It also enables the creation of software tools to support the system: you can't write a script to validate your system if you don't have a list of rules against which to validate.

These rules need to survive the real world. Let's be honest: they need to survive Obsidian. Obsidian is just a nice way to view Markdown files, so really what we're saying is that these rules need to survive arbitrary text files on disk. We need to imagine those text files as a database, even though they're not one.

Defining an ID

One such rule seems simple enough: an ID – which I'll refer to generically as an 'entry' in your system – is defined as AC.ID Title,1 e.g. 11.11 I am ID eleven-eleven.2

From here, we already know that we need 2 more definitions:

  1. The definition of category 11, which we store as 11.00 Title of category 11.
  2. The definition of area 10-19, which we store as 10.00 Title of area 10-19.3

Folder structure

You might optionally choose to store these text files in a nested folder structure.4

10-19 Area ten through nineteen/
   └── 11 Category eleven/
      └── 11.11 I am ID eleven-eleven.md

In which case, ID 11.11 must be a child of folder 11, which must in turn be a child of 10-19.

But if you want to leave all your files flat in a folder, that's a style choice. It breaks no rules.

So far, nothing new. Just setting the scene.

What about additional notes?

If you've used your system for any amount of time you know that notes can get full. It can be nice to create a new file so the main file doesn't get unmanageable.

Let's start using a real example, Life Admin's 11.11 Birth certificate & proof of name (which I'll shorten for convenience).

We just said that 11.11 Birth certificate defines the ID. So I can't just create another note called 11.11 Notes from applying for copy of UK birth certificate, because now I have 2 notes with ID 11.11. Which one defines the ID, and which is just a note? There's no way to tell.

Proposal 1: ~ is used to indicate a freeform sub-note

Any file containing notes, that is not the definition of the ID, and is not an EtE note (see below), must be named:

  • AC.ID~ Arbitrary title of sub-note

AC.ID Title must exist, in order to define the ID.

Freeform sub-notes MAY NOT contain Johnny.Decimal system metadata.5 All metadata is inherited from the parent ID. (You may do as you please with your own metadata/frontmatter.)

You may think of a sub-note as functionally identical to text inside a heading of the main note.

Valid: notes inside the ID note

# 11.11 Birth certificate

## Notes from applying for UK copy

I called the service centre and spoke to Dave and he said…

Equivalent: sub-note extracted to its own file

# 11.11 Birth certificate

// is now an empty note
# 11.11~ Notes from applying for UK copy

I called the service centre and spoke to Dave and he said…

Proposal 2: + means 'extend-the-end'; defining 'extend-the-end'

The system has had the concept of extend-the-end (EtE) for a few years. It's useful, but I've never been totally comfortable with its definition until now.

The canonical EtE example has always been your kids, in the context of the Life Admin System (LAS). There we have 11.11 Birth certificate. You have a kid, and at 6 months it's a touch young to be managing its own Johnny.Decimal system – one day! – so you do it. How do you store the kid's birth certificate?

The answer is 11.11+ Belinda.6 Because she'll also need her jabs, which you'll store at 11.25+ Belinda. Maybe you open her a savings account and you track it at 13.42+ Belinda.

You can think of these extended IDs as sitting on top of your primary system; like a shadow system. You've got your system, and overlaid with these + entries you have Belinda's system. And this is why it's called extend-the-end. You're just giving yourself a little more room.

Now, to find all entries in your system that relate to Belinda, just search for + Belinda.

Formalising how you extend-the-end

So when should you EtE with +, and when should you create a sub-note with ~? The answer is: when you'll have multiple instances of the thing through your system, use +, and always name them identically. Otherwise, use ~ and you are free to name them arbitrarily.

Our examples already demonstrate this. Will any other IDs require a note whose title is, or is even remotely like, Notes from appling for UK copy of birth certificate? Obviously not: use ~.

Will we use + Belinda over and over? We will.

You should be able to list all of your extend-the-ends

Your system must necessarily contain a finite number of EtEs, and you should be able to list them all. This is what makes them useful: you're defining a type of sub-note that you can easily filter on.

At home:

  • + Belinda, + Marie, + Wendy for each of the kids.

At work:

  • + Work log is a note where we record the fact that we did some work on a thing; typically with a date/timestamp.
    • E.g. 21.35 JDHQ has 21.35+ Work log
  • + P5 ideas is a note where we record ideas that aren't solid enough to make it into our task system.7
    • E.g. 21.35 JDHQ has 21.35+ P5 ideas
  • + Meeting minutes is a note where we record minutes of meetings that relate to the ID.
    • E.g. if we have a meeting specifically about JDHQ we might store the minutes at 21.35+ Meeting minutes.

Standards-in-waiting

Note that these work EtEs are likely to become recommendations of the system, i.e. if you have a need for a work-log-like note, don't call yours + My work-log. Call it + Work log and now we're all talking the same language.

In this way they become a bit template-like. We'll develop this into the Small Business System (SBS) over time.

Be consistent

Don't use + Belinda sometimes and + Bel elsewhere. Pick one.

A counter-example

As a counter-example, the SBS has ID 11.31 Internal policies. Our business has a sub-note 11.31~ Purpose, mission, values: this is the only ID that will require a note with that title, so it doesn't earn a +.

Below it our 11.32 External policies has 11.32~ Code of conduct, 11.32~ Privacy policy for the same reason.

Whereas if we had a meeting about these policies, we would store its minutes at 11.32+ Meeting minutes.

You own everything after the +

Parsing software will detect the + and consider it and anything that follows until the end-of-line to be the EtE pattern.

This means you are free to use a space, or to omit one. I have found that it feels natural to use a space when what follows is a sentence/word, and to omit one when what follows is a code. But this is guidance, not a rule.

An example of a code

The EtE concept was born at a job where I was dealing with 13 physical facilities. Each of those facilities had a well established shortcode e.g. E32, K07.

The Johnny.Decimal system as designed contained IDs like 53.07 Hardware delivery and 72.02 Cabling. To handle these things at each location, I extended the end:

  • 53.07+E32 was hardware delivery to E32.
  • 72.02+K07 was cabling at K07.

This worked beautifully. I used the IDs everywhere, across my notes, filesystem, email, and the project schedule. I could filter this schedule for +K07 to reveal all line items related to that facility.

In this case it feels natural to omit the space after the +. But if you prefer to include it, do so.

Keeping notes

Regarding notes, this works in the same way as the ~ sub-note.

Difference between ~ and +

To recap:

  • Both symbols provide a way to expand an ID that already exists.
  • ~ is for arbitrary, unpatterned expansion.
  • + is for systematic, patterned expansion.

In your filesystem

If you name your filesystem folders with the +, they sort in a group above any unstructured folders. This will probably be optional. I prefer it.

Proposal 3: @ links Work Packages to their ID

The updates to T&PM that we're recording include the concept of 'work packages' (WPs) as introduced in this video.

What's important here is a new nomenclature. Each WP has a number like W0000 but MUST also belong to a parent ID, 12.34. You MUST indicate this in the title, which ends up looking like:

  • W0011@12.34 Name of work package

Previously, we had used ~ as this divider. It works really nicely – it reads like 'work package 11 relates to ID 12.34' – but this is confusing if we also use it as the arbitrary sub-note symbol.

Instead, I propose using @ for this purpose. It also reads well: 'work package 11 at ID 12.34'.

In this context it will ALWAYS be nested between the range of characters defined by the regular expression /^W[0-9]{4}@[0-9]{2}\.[0-9]{2} \S.*$/, so you're still free to use it in your own titles, including EtEs.

How to feedback

Much appreciated. ✌🏼

Footnotes

  1. See AC.ID notation. ↩

  2. You can imagine these as .md files, but I won't write out the file extension. ↩

  3. If we want to name category 10 we need to use frontmatter inside this note. Unless specified, A0 categories are named Management of area $number. ↩

  4. System-management zeros not shown. 11.00 is a child of 11/; 10.00 is a child of 10/. ↩

  5. For example, a YAML block at the top of a Markdown file. ↩

  6. You're also free to duplicate area 10-19 Life admin for Belinda, giving her her own system. The reason many prefer EtE is that this new system of hers is going to be mostly empty. EtE is simpler and requires less management. ↩

  7. A P5 being one priority level below a P4, the lowest priority task. Ref. T&PM episode 'The P1-P4 system'. ↩