Situation: you’re writing documentation that you hope will help someone a year or more down the road.
Problem: you don’t know how to ensure this hypothetical future person will find the document you wrote.
Solution: create an entrypoint document for each major center (codebase, project, team, product, company) in your environment. The entrypoint document should consist of a short list of links to other, topical documentation. Put it in a prominent place and direct new teammates to it. That way, people will be able to find the docs they need, and you will have a framework on which to hang new documentation.
What a “prominent place” means depends on the type of center you’re documenting. If you’re writing an entrypoint for…
an in-person team: consider hanging up a poster in the team’s workspace with a minified link.
a distributed team: pin a post in the team’s chatroom or main communication channel. Slack now associates a “canvas” — basically a collaborative text document — with each channel, which you can use for this purpose.
a codebase: README.md in the repository root directory.
a part of a codebase: maybe a README.md in the relevant directory, though this can be hit-or-miss as far as finding it later goes. I wish IDEs drew your attention to this type of documentation as you browsed the code.
a project: wherever collaboration on that project primarily happens. This might be your issue tracker, chatroom, office space, discussion forum, or GitHub repo.
a product or company: an internal website (or maybe even a public one!) that everyone visits during new hire orientation.
A general rule: keep the documentation close to the thing it’s describing. Put it somewhere people visit often. A common antipattern is to document code in a separate CMS. This is bad because it separates the documentation from the thing being documented, making the docs harder to find and less likely to be updated.
A possible failure mode is that the entrypoint document gets way too big for anyone to comprehend. Aim for seven links on the page, plus or minus two. Keep ‘em high-level. Example:
# Welcome to <project name>!
- Emergency contact in case of a production issue: <link>
- Main chatroom (ask for help here): <link>
- Onboarding guide: <link>
- UI designs: <link>
- Issue tracker: <link>
- Codebase: <link>
- Staging server: <link>When you create new documents, link to them somewhere in the tree rooted at the entrypoint doc, but don’t add them to the entrypoint itself. Keep the hierarchy shallow. If you have seven links on each page, then 3 levels of hierarchy have room for over 300 pages. If you need more pages than that, it’s better to increase the branching factor than to increase the tree depth.
Another possible failure mode: you end up with several entrypoint documents, with team-, project-, and code-centric links all jumbled together, and no clear source of truth. The fix is to clearly delineate what each entrypoint is for, and move links where they belong. Each entrypoint page will probably still link to the others; that’s fine.
No matter what you do, there is a chance that future generations won’t even be able to find your entrypoint document. There’s no technocratic solution to this. The ultimate source of cultural continuity is always oral tradition upheld by people and their interactions. So keep talking to each other.
Further reading
The “strong centers” property of living structure, from Christopher Alexander.
Examples
Pivotal Labs practices (a company-wide entrypoint)
Arguably, my web portal page is the entrypoint document for my life. It gets away with violating the 7 +/- 2 rule because a) I am the only user, b) it has search, and c) I update it daily, so it stays fresh in my mind.