A setup for a large software org

Sharing your setup
1

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

  1. Easy to find documentation around services
  2. Easy to find files for a project.
  3. 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.
2

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.
3

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 30s and 40s 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…

4

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 40s (services) have a semi-standard code, not the 30s (projects) or 50s (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:

  1. 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.
  2. 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.
  3. 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/
└── ...
5

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.

6

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! :+1: