In our last post, we discussed why most shops poorly organize documentation. To sum up, we live in a world where search “just works” in most cases–except for our documentation. The solution is to fall back on sorting and organizing.
We went over the highest level form of organization, the PARA system. In this post, we’ll drop one level down and describe what things should look like under your top-level PARA folders.
Johnny Decimal
The Johnny Decimal system is a simple play off the Dewey Decimal system.
Here’s where you need to do some thinking. The creators suggest at least a week; but it could be longer depending on your organization’s size.
Or Just Get Started Alternatively, you may just want to start organizing but ensure you’re using a tool that makes things easy to refactor. Try moving some pages. Do links break? Is it easy? Do things get corrupted? The more robust the system is, the sooner you can start because you can just refactor to the ideal.
Johnny Decimal starts by breaking each of projects, areas, resources, and archives into up to ten sub-categories. These categories are whatever you think they ought to be.
It does not need to be 10, and it may be easier to have fewer than 10, especially in the beginning.
Once you have your ten main categories (for instance, “Accounting,” “Engineering,” and “Product”) you break each of those into, at most, ten more categories.
This gives each document a two-digit code of where it belongs. Let’s say inside “4 Engineering,” you have a sub-category called “7 Coding Standards.” Someone wants to introduce elixir and has drawn from some resources to develop a coding standard for elixir.
That document would get a designation of 47.
Since there are only 100 options for each project, area, resource, and archive, users will memorize common numbers relatively quickly. Moreover, there’s only one place and one place only to put (or search for) any document.
You can go further and put a sequence ID in the document number.
So, if this were the 30th document in the engineering (4) code standards (7) bucket, its total number might be 47.30.
These sequence IDs can help sort files in folders since it’s just the whole AAA plumbing trick except applied to documentation. Often “alphabetical” is the only sorting option many systems support, which is useless. If your documentation system allows arbitrary sorting, you may not need the sequence ids.
To differentiate between PARA folders, you can use P47.30, A47.30, R47.30, and C47.30 (for arChive).
Putting It All Together
You’ve got up to 400 buckets in this system; hopefully, you won’t need nearly that many. Indeed, it’d be good to keep things small initially.
Let’s say you’re just a department head, or even just a manager. How do you use this system?
Well, despite my saying, “try not to make departmental designations,” you’ll have to start there. So, let’s say you’re the head of product. You’d start with what will become the product folder in the areas folder. You won’t have PARA for just product.
You’ll also probably be thinking about what projects would go in the company’s projects folder.
So inside the product area, you’ll have up to ten sub-categories. Maybe one for the product design process at your company and another for ideal client profiles and segments. Perhaps one on product strategy.
Each of those folders will have up to ten subfolders themselves. (You may not need that many.)
As you’re solidifying the schema, remember: it may be worth thinking a week about this and talking to folks. Once the overall schema is in place, you can begin to organize what docs you currently have into the new schema. Ensure people put new docs in the correct place until the habit sticks. Regularly review the schema to ensure it’s helping people find what they need.
You might also be adding two or three projects to what will eventually be the projects folder. Each of those folders may have up to ten folders of ten folders for various aspects of the project. Again, hopefully, it won’t be that much.
A Note on Architecture
I’m using documentation architecture here to mean the system and relationship of tools you use to handle your documentation.
Even a medium-sized business will have an architecture that’s not trivial.
For instance, much of your written docs might be in Confluence or similar. However, many docs for code feel better on Github. Third-party information is often easiest to upload into Google Drive. Some spreadsheets and official docs you use to generate PDFs may also live in Google Drive. Finally, some project documentation will live in JIRA, while others might live in Confluence.
We’re about to get into a technique that can help simplify documentation architecture; but you also want to start talking and thinking about some standards from the start.
I’m usually not one to push standards early. However, if there’s any early agreement about what should belong where, it needs to be part of your PARA and Johnny Decimal training.
You don’t want someone to search P47 and find nothing, only to be told, “Oh, that’s in Github.” Think about what docs belong where.
I prefer to try and keep any docs in a single tool if possible, using other tools solely for what they and they alone can do. So, no internal docs in Google Drive, only documents that users may send outside the firm (if you’re not setting up public permissions in Confluence). Also, consider only detailed documentation in Github and broad design overviews in Confluence, for example.
On the flip side, some might argue that–for instance–Github’s peer review tool makes it ideal for watching versions of important docs like office policies. Have these discussions. When in doubt, push for simplicity. Simplicity is defined as “fewer rules and concepts” any new person has to memorize.
One Source of Truth and Liskov Substitutability
Ideally, only one system is your primary source of truth. To emphasize this, you can put backlinks from other systems back to your primary source.
For instance, if you’ve decided that Confluence should be the default source of truth, then Github should backlink to Confluence pages for projects related to a Github repo.
Can you put links from Github to other third-party resources, even if Confluence is the “source of truth?” Sure, but apply the object-oriented software principle of Likov Substitutability.
Any outgoing link (to more complicated Github stuff) should also be in the Confluence. There shouldn’t be anything high-level or outgoing on your Github that isn’t also in the Confluence source of truth.
This practice can lead to duplicate links, so why would you do it? The only reason to ever do this is just for ergonomics. In other words, it saves you a click. That’s a perfectly valid reason to add a link. Just make sure anything you add is also in the “one source of truth” so people can find it and that your subsidiary sources of truth link back to the “one source of truth” for navigation.
A subsidiary source of truth can have fewer “high-level” resources and outgoing links; but it can’t have more. Indeed, it can have more “detailed” links to itself.
Network Effects
We’ve covered the most important means of organizing your documentation. Daresay, we’ve covered your organization strategy. The other two means of organization, links and tags, are at most tactics.
While hierarchy is single inheritance, links are composition/aggregation. They’re like pointers.
You can have as many as you like, and all that link complexity is hidden safely inside a document. Only when someone opens that page do they see all the links. Links are excellent; there’s value when someone is willing to do the work to add them.
Still, they are work.
I want to focus on one particular kind of page that can serve as a landing point for your PARA+Johnny Decimal system. It can serve as a solution to the aforementioned architectural complexity problem.
The Map of Content
A Map of Content is a curated list of links, tables, graphs, and other bits to make. It functions as a homepage for any particular PARA+Johnny Decimal topic (or anything of sufficient complexity).
It will take some work because someone has to intentionally go about and gather interesting links. However, dashboards and homepages are handy when designed correctly.
If you have your PARA+JD system in order, the next step you’d want to take to improve it is to have at least one MOC at each endpoint. So, you’d have one MOC for 47 engineering/code standards. This might introduce links to the various adopted code standards, resources where arguments for and against code standards on quality are made, Github pages that demonstrate tooling that automatically checks for code standards, and so on.
Links can go anywhere and do anything. That’s their superpower. You want your MOC ideally to fix all the problems your documentation system has.
Folders can have multiple MOCs. Each MOC would, ideally, represent some interesting topic.
For example, you may have two subcomponents of a project you’re working on that don’t justify an entire folder. But they may each have a MOC that, in turn, links to docs on their design and their interrelationship.
Ideally, each MOC would have a single author. You can apply the concepts of code stewardship here–someone is responsible for maintaining the MOC, but they do so for the benefit of others. They don’t “own” it per se and do not operate it for their benefit. They do it for the benefit of others.
Indeed, docs are often where the rubber meets the road on developer experience. How do I find out the answers to my questions? These docs need to consider other developers as the users. They should use design thinking and product principles to serve those users.
The “default” MOC for a folder is what files appear in the folder. For simple things, this may be enough. But it doesn’t take a lot of complexity to benefit from a guided tour inside a folder (with nice formatting and maybe some graphics drawn from JIRA or Datadog).
Teams can have their own home bases as MOCs. Remember how I said departments don’t own folders? They can own MOCs, though. So if the accounting team has a separate list of links or dashboards they want to see, they can put their MOC inside the accounting area.
MOCs are better than mere folder dropdowns of all the files in the folder since they can link to any part of the docs (across folders) and to third-party resources. Good documentation tools can pull in nice pictures and other tools to make MOCs even more helpful.
You want your MOCs to be the webpage your team goes to routinely. You are designing a tool for them to do work well. It’s great to link to their essential JIRA queries, HR tools, Google Drive, and any tools you can.
Similarly, projects can link to the relevant Github pages and Datadog graphs.
Be sure to backlink where you can! Github pages should link back to the project MOC! This ensures that anything you can find on the MOC, you can find from anywhere you control that connects to the MOC.
Next week, we’ll review the dark arts of tags and how to start rolling out this system. Stay tuned!
We’re on a mission to make jobs suck less, one software management tip at a time. We need your help!
Do you want to stay up to date on the latest management tips to help your team stay productive?
Click “Subscribe to the Soapbox” below for more!
.png)
Comments