development-hub/templates/updating-documentation.md.template

---
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.

<!-- PRIVATE_START -->
## Internal Notes

This section is stripped from public builds.
Credentials, internal discussions, etc.
<!-- PRIVATE_END -->

## 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.