Managing documentation in an engineering department is not trivial. Many teams start with great intentions, only to get to the point where they have a pile of documentation that no one is using.

Use this list of practical tips to create an engineering documentation system that works. These concrete best practices come from real life practice, and have led to a living and useful documentation system at multiple software engineering departments.

• Documents go stale and need to be maintained. Anyone can edit anything (barring sensitive and legal things). Enforce a culture of shared documentation ownership from the first week on the job. Each new hire needed to either make one edit, or point out one mistake or improvement in the onboarding documentation they were using during their first week.
• People want to organize documentation, and they usually use a hierarchy to do it. While many things fit in a hierarchy, sooner or later something won’t. It either will lack a sensible place, or will belong in more than one place. Don’t limit yourself to a hierarchy. It will make people feel constrained. Choose a documentation tool that allows you to have a hierarchy, but also allows hyperlinking, tagging, and searching. Notion is my favorite, but many others do the job well also.
• Most companies don't suffer from a lack of documentation. Most documentation sits unused, becomes stale, and becomes useless. Make information discoverable. Change your perspective. Don’t think about who will write the documentation and how they will write it. Think of who will look for information and how will they find it. When people look for information, they either follow a “path” from some starting point, or they use the search feature. That means that a document is linked to from places where people are likely to search for it. That also means having a decent search. Analogy: if you are thinking where to store a newly-bought frying pan, you will think "kitchen" and then "cabinet" and then "where the other pots are".
• Use a concept of a documentation "hub". The main hub is your company's or department's documentation "home page". From there link to department documentation hubs. Each department hub might have team hubs, and process hubs, like "hiring" or "SDLC". Each project can have a hub. The following hubs were very helpful in organizing documentation and work
  • Engineering department hub - main starting point
  • Team hubs for each team, squad, pod, or whatever you call your functional teams
  • DevOps hub
  • QA hub
  • Onboarding hub
  • Hiring hub
  • HR hub - perks, policies, procedures specific to the engineering department
  • System hubs
    • Infrastructure
    • Any specific subsystem, e.g. message queue hub, search feature hub
  • Product feature hubs
    • Sometimes these aligned with team hubs, but at other times they were separate
  • Process hubs
    • Branching strategy
    • CI/CD
    • Coding best practices
  • Manager’s hub - this one had limited access to all managers
  • Project hubs - for bigger projects and initiatives. For smaller ones, a single page or
• Hyperlink everything. Learn "CMD-K" or whatever keyboard shortcut is used to create a hyperlink. The more you hyperlink, the more likely that someone will find the document they are looking for. Praise people for adding links to documentation and messages. Give feedback to people who do not do this. Make hyperlinks a habit. A small list of things that you can hyperlink that will make your life easier is below.
  • online spreadsheets
  • documents on OneDrive, Google Drive, or other shared storage
  • lessons in your LMS
  • external articles on the web
  • books on Amazon
  • Jira stories or epics
  • specific Slack conversations
  • GitHub tickets
  • Automated test run failure reports
  • post-mortems
  • video recordings of meetings
• Hyperlink everything! This one is worth repeating. You can add hyperlinks to most of the systems listed above as well. Slack messages can (and should!) have hyperlinks. A spreadsheet cell can be a hyperlink. Comments in a video can have hyperlinks. Jira, Slack, and many other developer tools allow for hyperlinking. When you spend 5 extra seconds adding a hyperlink when writing a message, comment, or post, you save literal minutes for every person who might need to see the thing you are referring to. The math adds up. Hyperlink everything!
• Don’t bother moving everything into “the one true documentation system.” Store things where they are and create hyperlinks to them. Use your main documentation system as the default place for new documentation. Create your hubs in your main documentation system. Don’t transcribe or copy everything back into your main documentation system. Use hyperlinks to link to resources outside of your documentation system. Build a rich context of information in the systems where it resides.

This is a particular philosophy that worked well. This is not the only true way. When the team followed these practices, documentation was maintained, and people were able to find it when they needed it. Feel free to use it all, or pick and choose parts. If you take only one thing away from this, it’s “hyperlink everything.”

💡Pro tip

Many programs have the same keyboard shortcut to turn text into a hyperlink. Start by copying the URL to which you want to link. Then select the text you want to turn into a hyperlink. The shortcut is usually one of the following:

• ⌘-K (on Mac) or CTRL-K (on Windows) will open a window to add and hyperlink and create a URL. Many programs use this shortcut, including Microsoft tools like Excel.

• ⌘-V (on Mac) or CTRL-V (on Windows) will immediately turn the selected text into a hyperlink to the URL you copied previously. Slack and Notion, and some others work like this.

Google "How to insert hyperlink in YOUR PROGRAM" to find out exactly how to do it