How do you structure your page trees for internal knowledge bases for processes or software?

Patrick Haley December 8, 2021

I'm always curious how other people decide to design their knowledge base page trees. Ideally, it would make sense to both technical and non-technical viewers (even if they don't always all of the content like database schemes, etc).

For more complex projects we use something similar to this:

  • Team & Communication - This is an overview of the project
  • Development - different pages for test data, system architecture, new dev guides/resouces, dev/uat/stg/prod infrastructure, integration points, 3rd party components, etc.
  • Meeting Notes - internal/external meetings related to the project
  • Project Management - estimations, project plans, etc
  • Quality Assurance - overviews of qa environments, reports, testing plans, etc
  • Requirements - Technical requirements for the application; This is where most of the content lives. 
  • Retrospectives - mostly meeting notes from the dev team
  • Trackers - decisions, change requests, glossaries, dictionaires, external documents, scheduled tasks, etc.

For less complex projects we use something like this (adapted from this article):

  • 00 - About - General introduction and overview of the project, team and communications
  • 01 - Roadmap - All things related to planning and specifications. This is the main working area for the analysts and will contain things like backlogs, wishlists, functional specs for a future version etc. This is the main area where you will find the actual projects.
  • 02 - Development - Groups everything that someone needs to know to be able to develop on the application. Note that a technical analysis for a specific story to be implemented does not belong here, a technical overview of how something is implemented does.
  • 04 - Release Notes - This section gives an overview of the entire release history.
  • 05 - Maintenance & Support - This section groups all documentation relevant for operational (technical) support of the Knowledge Base. Ideally, this is enough so a team member without knowledge of the inner workings can offer basic support (like editing articles, check log files, etc).
  • 06 - User Documentation - Contains all end-user documentation like manuals or public API's.

Just curious how those more experienced handles this and I'm looking for ideas and best practices we should start following. 

1 comment

thekeithlane June 10, 2022

Hi! Thanks for your post in listing your internal page structure. I was looking for best practice examples. One or our requirements building out the below table of contents was that it would be designed for technical and non technical team members to be able to navigate. Here is a navigation tree I developed with my team in my last company.

It was a challenge managing it as we grew, as the laws of entropy strike first in documentation and there are always other tasks that seem more important than playing a librarian - though it was worth it for our team.

* Introduction

* Onboarding Overview

* Training

* Teams

* Ceremonies & Meetings

* Initiatives & Projects

* Process and Procedures

* Testing

* Release Management

* Production Support

* Business Capabilities And Tech Components

* Terminology

* Miscellaneous

* Confluence Feedback

* Product Refinement Process

* Ideas for Machine Learning

* SRE

* L1/L2 Production Support How-to articles

* Platform Applications

* Product Strategy

* Run Books

Comment

Log in or Sign up to comment
TAGS
AUG Leaders

Atlassian Community Events