--- sidebar_label: Updating Documentation sidebar_position: 99 --- # How to Update Documentation This document explains the documentation system and procedures for updating {{PROJECT_TITLE}} documentation. ## Documentation Architecture {{PROJECT_TITLE}} documentation is managed through a **centralized documentation system**: ``` ~/PycharmProjects/project-docs/ # Central documentation hub ├── docs/projects/{{PROJECT_NAME}}/ # Docs source (THIS FOLDER) ├── scripts/build-public-docs.sh # Builds public docs └── public-builds/{{PROJECT_NAME}}/ # Built static site ~/PycharmProjects/{{PROJECT_NAME}}/ └── docs -> ../project-docs/docs/projects/{{PROJECT_NAME}}/ # Symlink to here ``` ## Two Documentation Modes ### Private Documentation (Internal) - **Location**: `~/PycharmProjects/project-docs/` - **View locally**: `cd ~/PycharmProjects/project-docs && npm start` - **Contains**: All docs including credentials, internal notes, todos, deployment details - **Audience**: Internal team only ### Public Documentation (Contributors) - **Location**: `https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/` - **Build command**: `~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy` - **Contains**: Only whitelisted public files - **Audience**: Open-source contributors ## File Visibility Rules ### Automatically Public Files These filenames are included in public builds: - `overview.md` - `architecture.md` - `formats.md` - `configuration.md` - `index.md` ### Making Other Files Public Add frontmatter to include a file in public builds: ```markdown --- public: true --- # Your Document Title ``` ### Hiding Sections Within Public Files Use HTML comments to hide sensitive sections: ```markdown ## Public Section This content is visible to everyone. ## Internal Notes This section is stripped from public builds. Credentials, internal discussions, etc. ## Another Public Section ``` ## File Format Requirements The Development Hub dashboard parses certain documentation files. These files must follow specific formats for the parsers to work correctly. ### goals.md Format ```markdown --- type: goals project: {{PROJECT_NAME}} updated: YYYY-MM-DD public: true --- # Goals ## Vision Optional prose description of the project vision. ## Active - [ ] Goal description #high - [ ] Another goal #medium - [x] Completed goal #low ## Future - [ ] Future goal idea - [ ] Another future consideration ## Non-Goals - **Thing we won't do** - Reason why - **Another non-goal** - Explanation ``` **Key rules:** - Use `## Active` and `## Future` section headers (parser looks for these) - Goals must use checkbox format: `- [ ]` or `- [x]` - Priority tags: `#high`, `#medium`, `#low` (optional, defaults to medium) - Non-goals use bold text with dash explanation ### todos.md Format ```markdown --- type: todos project: {{PROJECT_NAME}} updated: YYYY-MM-DD public: true --- # {{PROJECT_TITLE}} TODOs ## Active Tasks ### High Priority - [ ] Important task @M1 - [ ] Another urgent item @M1 ### Medium Priority - [ ] Regular task @M1 ### Low Priority - [ ] Nice to have @M2 ## Completed - [x] Done task @M1 (YYYY-MM-DD) ## Ideas / Backlog - Future idea @M2 - Another concept @M3 ## Known Issues | Issue | Status | Workaround | |-------|--------|------------| | Bug description | Investigating | Temp fix | ``` **Key rules:** - Use `### High Priority`, `### Medium Priority`, `### Low Priority` headers - Todos use checkbox format: `- [ ]` or `- [x]` - Milestone tags: `@M1`, `@M2`, etc. (optional) - Completed items should include date in parentheses ### milestones.md Format ```markdown --- type: milestones updated: YYYY-MM-DD --- # Milestones ## Active #### M1: Milestone Name **Target**: January 2026 **Status**: In Progress (80%) **Notes**: Optional notes | Deliverable | Status | |-------------|--------| | Feature A | Done | | Feature B | In Progress | | Feature C | Not Started | --- ## Completed #### M0: Previous Milestone **Target**: December 2025 **Status**: Complete ``` **Key rules:** - Use `#### M#: Name` format for milestone headers - Status values: `Not Started`, `Planning (X%)`, `In Progress (X%)`, `Complete` - Deliverable status: `Done`, `In Progress`, `Not Started` - Separate milestones with `---` ## Procedures ### Adding New Documentation 1. Create the file in `~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}/` 2. Add appropriate frontmatter (title, sidebar position) 3. If it should be public, either: - Use a whitelisted filename, OR - Add `public: true` to frontmatter 4. Preview locally: `cd ~/PycharmProjects/project-docs && npm start` ### Updating Existing Documentation 1. Navigate via symlink: `cd ~/PycharmProjects/{{PROJECT_NAME}}/docs` - Or directly: `cd ~/PycharmProjects/project-docs/docs/projects/{{PROJECT_NAME}}` 2. Edit the relevant `.md` file 3. Preview locally if needed ### Publishing to Public Site ```bash # Build and deploy {{PROJECT_NAME}} docs only ~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --deploy # Or build all projects ~/PycharmProjects/project-docs/scripts/build-public-docs.sh --deploy # Dry run (see what would happen) ~/PycharmProjects/project-docs/scripts/build-public-docs.sh {{PROJECT_NAME}} --dry-run ``` ### Viewing Documentation ```bash # Private docs (all content) cd ~/PycharmProjects/project-docs && npm start # Opens http://localhost:3000 # Public docs # Visit https://pages.brrd.tech/{{GITEA_OWNER}}/{{PROJECT_NAME}}/ ``` ## For AI Assistants When asked to update documentation for this project: 1. **DO** edit files in `docs/` (the symlink) or the full path above 2. **DO NOT** create documentation files in the project root 3. **DO** use appropriate visibility (public/private) based on content 4. **DO** run the build script if publishing changes to the public site 5. **DO** preview changes locally before publishing The `docs/` folder you see in this project is a symlink to the central documentation system. All changes are reflected in both the private hub and (after building) the public site.