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 here are a small set of bounded, core, cross-cutting company efforts outside routine delivery, such as shared CRM systems, financial visibility, or the company KB rollout. They live in projects/.

Campaigns, monthly cycles, routine operations, product releases, and client or product delivery belong in their execution trackers. Keep a concise summary and a tracker link on the initiative rather than adding a project page here. Historical records retired from this portfolio live in the repo-only docs/plans/retired-projects/ folder.

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 only when the work is core, cross-cutting, outside routine delivery, and has a clear done state or review point. A deadline alone does not qualify an effort for a project page.

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

Confirm the effort meets the core, cross-cutting, non-delivery scope above, then 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

Repository versus published site

Retained company knowledge is published. Delete obsolete drafts, abandoned workstreams and superseded duplicates rather than hiding their folders. Preserve useful outcomes and source links on the relevant initiative when removing a duplicate.

Publication exclusions are for material that supports working in the repository: agent instructions, tooling, task tracking, internal plans and handoffs in docs/plans/, and social-skill context/examples. An exclusion is a deliberate retention decision, not an archive for irrelevant content. The retained dated meeting and client-feedback records are evidence, not current task lists.

Useful company references include distribution locations, launch submission requirements, the anchor-moment process, and its dated cycle log.