I’m in a large software organization – close to the Dunbar number – split across several teams and owning many software services.
We have many ongoing projects per year; usually spanning multiple services, often spanning multiple teams.
My tenets for J.D. in order
- Easy to find documentation around services
- Easy to find files for a project.
- Keep it 2 levels deep – leave the three-level monikers for individuals’ systems.
10 Health and Career/
├── 11 Work life balance/
├── 13 Career Growth/
└── 14 DEI/
20 Customer Contact/
├── 21 Customers Information and Onboarding/
├── 22 Customer meetings/
└── 23 Office Hours/
30 Campaigns and Projects/
├── 3+P21 Operations/
├── 3+P22 Operations Reduction/
├── 3+X29 Scaling for Customer X/
│ ├── 3+X29.01 Requirements
│ ├── 3+X29.02 Design
│ ├── 3+X29.03 Tracking
│ ├── ...
│ └── 3+X29.15 Post-mortem
├── 3+M41 Storage migration/
├── 3+A10 Archive Tuning/
├── ...
└── 3+Z99 Retired Projects/
40 Service Documentation/
├── 4+R07 Router/
│ ├── 4+R07.01 Tenets
│ ├── 4+R07.02 Architecture
│ ├── 4+R07.03 Code Repositories
│ └── 4+R07.04 Operations Dashboards
├── 4+C2X Control Plane/
├── 4+Z12 Archiver/
├── 4+X11 Index/
├── ...
└── 4+Z99 Retired Services/
50 Team Documentation/
├── 5+A01 Apple/
│ ├── 5+A01.01 Operations Dashboards
│ ├── 5+A01.02 New Hire Guide
│ ├── 5+A01.03 Kanban Boards
│ ├── 5+A01.04 Ticket Queue
│ └── 5+A01.05 Resources
├── 5+B06 Bridge/
├── 5+C08 Canyon/
├── 5+M02 Maple/
├── 5+M07 Mountain/
├── 5+N03 Needle/
├── 5+S34 Sea/
├── 5+S45 Surf/
└── 5+T09 Tower/
60 Planning/
├── 61 Roadmaps
├── 62 Yearly planning/
│ ├── 62.01 2021
│ ├── 62.02 2022
│ └── 62.03 2023
├── 63 Quarterly Status
└── 64 Bi-weekly status
My analysis:
-
PRO It’s flat; technically 2 levels deep.
-
PRO Projects are grouped together, prefixed with
3
-
PRO Services are grouped together, prefixed with
4
-
CON The
3+A10
-style project categories seem a bit hacky; but 3.A10
feels more like an extra level and feels weird under the 30
area, in my opinion.
Two alternatives come to mind:
Alternative 1
As a simplification of the above, I note these particulars about my org:
- A service has a 2-5 letter prefix already associated with the hosts. Some people already refer to the service by this prefix instead of its name. I hate that. But I could use that for the service.
- Like so:
4.ROU.02 Architecture
4.IDX.04 Operational Dashboards
- I think I prefer the service name, though:
4.Router.02 Architecture
4.Index.04 Operational Dashboards
-
CON Neither roll off the tongue like vanilla J.D.
42.02 Architecture
-
CON An extra level of hierarchy that isn’t really needed
- A team already has a one-word name; why associate it with a random three-letter code?
5.Maple.01 Operations Dashboards
- Same problems as for the service about rolling tongues and hierarchy.
Alternative 2
Each area specifies how many digits are allowed for categories
1X Health and Career/
2X Customer Contact/
3XXX Campaigns and Projects/
└── 3-X29 Scaling for Customer X/
└── 3-X29.02 Design
4XX Service Documentation/
└── 405 Index/
└── 405.02 Architecture
5XX Team Documentation/
└── 511 Tower/
└── 511.02 New Hire Guide
6X Planning/
-
PRO flattens the hierarchy and gets rid of the three-letter pneumonic for services and teams. I don’t think those are needed. They probably are needed for projects, though.
-
CON The Librarian will have to fight entropy to keep the smaller areas from gaining un-needed digits. Hopefully having 7-9 open will help.
I prefer the first version. Something about those +
pluses that I quite like, can’t put my finger on it. Maybe it keeps the mathematical nature of the ‘original’ JD? Either way.
So is this a system that just you will be using, or will this be a shared company thing?
And presumably these 3-letter codes already exist? And are consistent across your 30
s and 40
s and so on?
I’d still like to see how this looked with those 3-letter IDs up at the top level, textbook PRO.AC.ID
style…
So is this a system that just you will be using, or will this be a shared company thing?
My company’s shared files are a mess. I want to clean it up for everyone.
And presumably these 3-letter codes already exist? And are consistent across your 30
s and 40
s and so on?
Only the 40
s (services) have a semi-standard code, not the 30
s (projects) or 50
s (teams).
I’d still like to see how this looked with those 3-letter IDs up at the top level, textbook PRO.AC.ID
style…
I have a few issues I am trying to resolve with this idea:
- Where do I organize those for the entire org? I had them embedded into the structure, otherwise I’m afraid it will turn into a 4-level deep structure.
- I figured each individual should be in charge of adding 3-letter-code/3-level-hierarchy to their own systems, and not have that dictated by the company.
-
D01.13.01
(link) says in bold: You should only use multiple projects if they are absolutely required.
Otherwise, it looks like so:
Projects and Campaigns/
├── P21 Operations/
├── P22 Operations Reduction/
├── X29 Scaling for Customer X/
│ ├── X29.01 Requirements
│ ├── X29.02 Design
│ ├── X29.03 Tracking
│ ├── ...
│ └── X29.15 Post-mortem
├── M41 Storage migration/
├── A10 Archive tuning/
├── ...
└── Z99 Retired projects/
Services/
├── ROU Router/
│ ├── ROU.01 Tenets
│ ├── ROU.02 Architecture
│ ├── ROU.03 Code Repositories
│ └── ROU.04 Operations Dashboards
├── CP Control Plane/
├── AR Archiver/
├── IDX Index/
├── ...
└── Z88 Retired services/
Teams/
├── CPY _Company & Common/
│ ├── 10 Health and Career/
│ │ ├── 11 Work Life Balance/
│ │ ├── 13 Career Growth/
│ │ └── 14 DEI/
│ ├── 20 Customer Contact/
│ │ ├── 21 Customer Information and Onboarding/
│ │ ├── 22 Customer Meetings/
│ │ └── 23 Office Hours/
│ └── 60 Planning/
│ ├── 61 Roadmaps/
│ ├── 62 Yearly Planning/
│ ├── 63 Quarterly Status
│ └── 64 Bi-weekly Status
├── MPL Maple Team/
│ ├── MPL.10 Operations and Dashboards/
│ │ ├── MPL.10.01 Weekly Review Dashboard
│ │ ├── MPL.10.02 Service Dashboards
│ │ ├── MPL.10.03 Ticket Queue
│ │ └── MPL.10.04 Runbooks
│ ├── MPL.20 Guides and Resources
│ └── MPL.30 Kanban/Sprint Tracking
├── BRG Bridge Team/
└── ...
I do like the original the best. I think a small tweak makes it better: Make the prefixes for projects, teams, etc the full two digits. For example, everything under 30 Campaigns and Projects
has the pattern 30+XYZ
so a file looks like 30+X29.02 Design
.
Yeah that feels better.
Look it’s obviously an adaptation of vs. the canonical JD standard, but whatever. If that works for you, go for it! 