How To Use The KB

This repo is Datopian's lightweight company knowledge base and portfolio tracker.

Use it to answer three practical questions:

what are we currently working on
how is that work structured
where is the canonical page for a given initiative or project

Start here

If you are new to the repo:

Open portfolio/README.md
Use the portfolio tree as the main overview
Open the initiative or project page you want to understand
Use the template docs only when you are creating or updating a page

What lives where

Initiatives

Initiatives are the long-lived things:

products
services
internal systems
capability areas
grouping initiatives

They live in initiatives/.

Projects

Projects are bounded work inside initiatives:

experiments
campaigns
versioned pushes
time-bounded implementation efforts

They live in projects/.

Portfolio views

The portfolio views are the navigational layer:

portfolio/portfolio-indented.html
portfolio/portfolio-map.html

They are generated from the markdown files in initiatives/ and projects/.

The tree is the default view. The map is optional.

Initiative or project?

Use an initiative if the work is ongoing.

Use a project if the work has a clearer done state, review point, or time boundary.

Where SCQH and plan fit

Default rule:

SCQH belongs at the initiative level
plan of work usually belongs at the project level

Use SCQH on a project only when the problem itself is unclear and needs deeper framing.

Minimum required information

Initiative minimum

Every active initiative should have:

title
owner
status
north_star
scqh
next_step
commitment
target_date
active_issue

If it sits under another initiative, add parent.

If it has active child projects, link them in the body of the page.

Project minimum

Every active project should have:

title
owner
status
parent
hypothesis
success_metric
definition_of_done
end or a clear timebox
active_issue

Use the body of the page for updates, evidence, related issues, and notes.

Quality rule

No active project should exist without:

a clear hypothesis
a clear success test
a clear done definition
a clear end date or review point
one canonical live issue

No active initiative should exist without:

a concrete commitment
a target date
one canonical live issue

Learning rule

Every finished or paused project or experiment should capture:

what we tried
what happened
what we learned
what we do next, if anything

How to add or update pages

Add a new initiative

Create a file in initiatives/
Use docs/initiative-template.md
Fill in the minimum fields
Add only the body sections that are actually useful
For active initiatives, include ## Current Commitment, ## Key Results, ## Milestones, and ## Related Issues

Add a new project

Create a file in projects/
Use docs/project-template.md
Make sure it has a clear parent initiative
Fill in the minimum fields
Use the body for updates, evidence, related issues, and notes
For active projects, include ## What this project is, ## Plan of work, and ## Related Issues

Update an existing item

edit the existing page directly
keep that page as the source of truth
avoid duplicating the same information elsewhere

Practical rules

keep the portfolio tree lightweight and navigational
keep richer detail on the item page itself
avoid duplicate overview docs
prefer concrete names over vague bucket names
every project should have a clear parent
keep templates lightweight, but not rushed
if a project cannot be assessed at the end, the template is too light
if an initiative cannot say what it is promising by when, it is not ready to be active

Accountability rule

The KB is not just descriptive. It is meant to support commitments.

That means:

active items should be reviewable at any time
owners should be able to explain whether they are on track
the CEO should be able to inspect promise, date, milestone, and issue quickly

Use portfolio-accountability-rhythm.md when running the team review or resetting the portfolio.

README.md
portfolio/README.md
docs/initiative-template.md
docs/project-template.md
docs/portfolio-accountability-rhythm.md
portfolio/structure-rationale.md