Skip to content

FLX-ENG-RFC-002-US-1.2 - Flexli Documentation Folder Access

Field Value
Parent RFC FLX-ENG-RFC-002
GitHub Issue #10 - US-1.2
Owner Arun Singh
Priority P2
Status Ready for validation
Target window Day 1

Goal

Confirm that Flexli engineering documentation can be read, edited, reviewed, and rendered through the existing MkDocs site.

Existing Docs Location

Use the existing docs tree:

  • docs/rfcs/ for RFCs and execution specs.
  • docs/developer-guide/ for developer workflow notes.
  • docs/runbooks/ for operational procedures.
  • mkdocs.yml for navigation.

Do not create a parallel documentation root.

Approaches Considered

Approach Pros Cons
Existing MkDocs tree Already in repo, reviewable, versioned Requires nav updates for new pages
External Google Docs only Familiar for business review Harder to review, branch, and preserve with code
Issue comments only Fast Not enough structure for handoff or Mac transition

Verdict

Use docs-as-code in this repository, then share rendered links or PR links with Raja/Shrikant.

Setup Steps

cd D:\work\repos\dms_ci_cd_test
python -m venv .venv
.\.venv\Scripts\python -m pip install -r requirements-docs.txt
.\.venv\Scripts\python -m mkdocs build --strict

On a new MacBook:

git clone https://github.com/Flexli-Technologies/dms_ci_cd_test.git
cd dms_ci_cd_test
python3 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements-docs.txt
mkdocs serve

Implementation Steps

  1. Update docs/rfcs/FLX-ENG-RFC-002.md if parent EPIC language changes.
  2. Add or update child specs in docs/rfcs/.
  3. Add all new pages to docs/rfcs/index.md.
  4. Add all user-facing pages to mkdocs.yml.
  5. Run mkdocs build --strict.
  6. Fix broken links before PR.

Test Cases

  • mkdocs build --strict exits 0.
  • RFC index links resolve.
  • Markdown tables render correctly.
  • No local-only paths are required to understand the spec.

Gating

  • No secrets or private credentials in docs.
  • No large raw scan outputs in docs unless scrubbed.
  • Every external action must include a GitHub issue number.

Definition of Completion

  • Docs access validated.
  • MkDocs build passes.
  • New RFC/spec pages are linked from the RFC index and site nav.

Reviewer Reply Template

Thanks, I kept this in the existing MkDocs tree so the docs stay reviewable with the PR.