Project Administration

Contributing to Wiltkey Docs

Guidelines for maintaining, extending, and keeping the developer documentation synchronized with the codebase.

Documentation Architecture

Wiltkey developer documentation is built as a self-contained, client-side static site inside the public website repository at github.com/ArtFacility/wiltkey-site. It runs completely offline without any compile or build steps. Code references correspond to the application codebase repository at github.com/ArtFacility/WiltKey.

📁 File Structure
  • docs/index.html: The documentation home page and search hub.
  • docs/assets/docs.css: The unified stylesheet implementing the Wiltkey design system tokens and layout styling.
  • docs/style-guide.html: The design system reference page illustrating all reusable tokens, typography, and container components.
  • docs/_coverage.html: The developer checklist detailing codebase file-to-feature coverage and verify mappings.
  • docs/[feature-name].html: Feature-specific documentation pages.

Required Page Template

To preserve visual and semantic consistency, every new feature page must follow this strict 5-section layout pattern:

  1. Overview: Define what the feature is and why it exists.
  2. How it Works: Provide a clear, chronological step-by-step walkthrough of the code execution path. Include inline SVG diagrams where necessary to visualize complex protocol states or memory layouts.
  3. Key Files & Symbols: Present a styled <table> mapping specific source file paths, class/function symbols, and their exact roles. Reference files with paths relative to the project root and do not use hardcoded line numbers.
  4. Gotchas / Edge Cases: Document unexpected side effects, platform quirks (e.g. background execution limits, BLE timing differences), or edge-case handling.
  5. Related Pages: List internal cross-links to contextually relevant documentation pages.
💡 PRO TIP FOR DIAGRAMS
Avoid external image files or complex javascript rendering libraries. Embed direct, clean inline SVG elements wrapped in the .diagram-container utility class to guarantee responsive rendering and match the site's dark palette.

Adding & Modifying Pages

When implementing a new feature or modifying existing codebase behavior, follow this checklist to update the documentation:

🔄 Step-by-Step Update Flow
  1. Check the Code: Remember that the code is the only source of truth. Never invent symbols, configuration variables, or file paths. If a feature or mechanic cannot be verified directly in the code, mark it with "⚠️ NEEDS VERIFICATION".
  2. Write the HTML: Reference docs/style-guide.html to copy structural elements (Sidebar, Layout wrapper, Headers, Callouts, Tables).
  3. Update Search Index: Open docs/index.html and locate the static INDEX_DATA JavaScript array. Append a new search record containing the page's URL, title, description, and list of keywords and symbols.
  4. Verify Coverage Map: Add or tick off the corresponding codebase file in the coverage checklist inside docs/_coverage.html (and docs/_coverage.md if applicable).
  5. Audit Links & Stamp: Perform a manual validation of all cross-page links, verify file references, and update the footer stamp to the current verification date: Last verified: [Date].