Skip to content

IMPLEMENTATION-DOCS.md

Latest commit

 

History

History
107 lines (83 loc) · 5.85 KB

IMPLEMENTATION-DOCS.md

File metadata and controls

107 lines (83 loc) · 5.85 KB
Raw

Implementation Documentation Standard

Every SPFx project in this workspace ships an Implementation Guide: a single document that lets someone with no SharePoint or Power Automate experience stand the solution up — SharePoint lists, Dataverse tables, Power Automate flows, package deployment, page setup, and a verification checklist — in one fixed format that is identical from project to project.

The one rule that makes documents consistent

Nobody writes the Markdown. Each project keeps a machine-readable source file, docs/implementation/implementation.json, and the shared generator renders the deliverable:

# from your clone of spfx-implementation-docs (npm install once)

# scaffold the source file (once per project)
node bin/spfx-docs.mjs --app ../my-project-spfx --init

# validate + render docs/implementation/IMPLEMENTATION.md
node bin/spfx-docs.mjs --app ../my-project-spfx

# validate only (CI / pre-commit)
node bin/spfx-docs.mjs --app ../my-project-spfx --check

npm link in this repo makes the command available anywhere as spfx-docs. Prefer calling it directly as shown — wrapping it in npm run … -- --app can swallow the flags on some npm versions.

Authors record data (column schemas, flow steps, prerequisites). The generator supplies the procedure — exact, novice-safe click-paths — and the fixed layout. Because every project renders through the same code, every guide has the same twelve sections, the same tables, the same phrasing. Format drift is impossible.

The source file is validated against schemas/implementation.schema.json (this repo) before rendering; schema errors are printed with their exact JSON path.

Central publishing. When a _implementation-docs folder exists at or above the project (ours: C:\Repos\ExecutiveOffice\_implementation-docs), every render also copies the guide there as <project>.md and refreshes that folder's index — the one place to find every guide.

The fixed document layout

# Section Filled from
1 Solution overview authored (project, architecture.description)
2 Prerequisites & access authored (prerequisites)
3 Architecture at a glance authored (architecture.components)
4 SharePoint lists — per list: create → column table → per-column click-steps → indexes → views → permissions → seed data authored (sharePointLists); click-paths generated
5 Dataverse tables authored (dataverseTables); click-paths generated
6 Power Automate flows — per flow: facts table → connections → trigger → step-by-step build → error handling → test authored (flows); designer phrasing generated
7 App deployment (tenant CDN rules baked in) auto from config/package-solution.json + config/write-manifests.json
8 Web part setup + property defaults auto from src/webparts/*/*.manifest.json
9 Site configuration authored (configuration)
10 Post-deployment verification checklist auto (lists, flows, web parts) + authored extras
11 Rollback auto baseline + authored extras
12 Glossary auto base terms + authored extras

Sections with nothing to say render "None for this solution." — the numbering never shifts, so readers always know where to look.

Quality bar (what "thorough" means here)

  • Internal names are contract. Column internal names come from the app's code (service $select clauses, constants files) — never from memory. The generated steps create each column under its internal name first, then rename to the display name, because SharePoint locks the internal name at creation.
  • No scripts for provisioning. This tenant blocks PnP PowerShell (Connect-PnPOnline fails under Conditional Access). Lists are created by hand in the browser; the guide's click-paths ARE the provisioning mechanism. Never ship a provisioning script as the deliverable.
  • Flows are reproducible literally. One steps[] entry per designer action, with the exact action name ("SharePoint → Get items") and a field-by-field configuration table. Include connections (and who should own them), error handling, and a test procedure.
  • A novice can finish. Plain-language summaries, glossary for jargon, and a verification checklist that proves the implementation before anyone calls it done.

Agent prompt — Build An Implementation Plan

Copy this into Claude (or any agent) in a project or workspace session:

Build an implementation plan for <project folder> following IMPLEMENTATION-DOCS.md in the
spfx-implementation-docs repo.

1. If docs/implementation/implementation.json is missing, scaffold it from the
   spfx-implementation-docs clone:
   node bin/spfx-docs.mjs --app <project folder> --init
2. Fill implementation.json from the REAL code — list column internal names and types from the
   services' $select clauses / constants files, flow dependencies from flowUrl properties and
   queue lists, prerequisites from what the setup actually requires. Plain language everywhere.
   Do not invent columns or flows; if a flow's steps are unknown, reconstruct them from what the
   app writes and reads and mark assumptions.
3. Render and validate:
   node bin/spfx-docs.mjs --app <project folder>
4. The deliverable is docs/implementation/IMPLEMENTATION.md plus the updated implementation.json —
   commit both (the tool also publishes a copy to the workspace _implementation-docs folder).
   Never hand-edit IMPLEMENTATION.md.

Reference implementations

In the Executive Office workspace:

  • org-chart-spfx/docs/implementation/ — list-centric example (one list, deep column schema).
  • subscription-service-spfx/docs/implementation/ — lists and Power Automate flows.

Open either implementation.json next to its rendered IMPLEMENTATION.md to see exactly how source data becomes the deliverable.