|
| 1 | +# Documentation Maintenance Guide |
| 2 | + |
| 3 | +This file describes when and how to update the hds-lib-js documentation in `docs/`. |
| 4 | + |
| 5 | +## Structure |
| 6 | + |
| 7 | +``` |
| 8 | +docs/ |
| 9 | +├── _config.yml # Jekyll configuration for gh-pages |
| 10 | +├── index.md # Library overview, architecture diagram, export list |
| 11 | +├── getting-started.md # Installation, setup, browser/Node usage |
| 12 | +├── settings.md # Settings module reference |
| 13 | +├── hds-model.md # HDSModel, items, streams, authorizations, event types, datasources |
| 14 | +├── app-templates.md # Detailed App Templates guide (Manager, Collector, Invite, Client) |
| 15 | +├── localization.md # Localization utilities |
| 16 | +├── toolkit.md # StreamsAutoCreate, StreamTools |
| 17 | +├── utilities.md # Duration, reminders, errors, logger |
| 18 | +├── assets/ # Images, SVG diagrams (if extracted from inline) |
| 19 | +└── MAINTAIN-DOC.md # This file (excluded from Jekyll build) |
| 20 | +``` |
| 21 | + |
| 22 | +## When to update |
| 23 | + |
| 24 | +### Always update docs when: |
| 25 | + |
| 26 | +1. **Adding a new public method/property** to any exported class |
| 27 | + - Add it to the relevant section with signature, description, and example |
| 28 | + - If it's in appTemplates, update `app-templates.md` |
| 29 | + |
| 30 | +2. **Changing method signatures** (parameters, return types) |
| 31 | + - Update the method documentation and any affected code examples |
| 32 | + |
| 33 | +3. **Adding a new module or class** |
| 34 | + - Create a new page if warranted, or add a section to the most relevant existing page |
| 35 | + - Update `index.md` exports table and architecture diagram |
| 36 | + - Add to `_config.yml` nav if it's a new page |
| 37 | + |
| 38 | +4. **Changing the appTemplates flow** (new statuses, new event types, new stream suffixes) |
| 39 | + - Update the sequence diagram, state diagrams, and SVG stream structure in `app-templates.md` |
| 40 | + |
| 41 | +5. **Changing CollectorRequest structure** (new properties, new section types) |
| 42 | + - Update the data structure diagram and property tables in `app-templates.md` |
| 43 | + |
| 44 | +6. **Adding or changing event types** |
| 45 | + - Update the event types table in `app-templates.md` and/or `hds-model.md` |
| 46 | + |
| 47 | +7. **Changing the data model integration** (new HDSModel sub-modules, new item properties) |
| 48 | + - Update `hds-model.md` |
| 49 | + |
| 50 | +### No doc update needed for: |
| 51 | + |
| 52 | +- Internal refactoring that doesn't change the public API |
| 53 | +- Bug fixes that don't change behavior |
| 54 | +- Test changes |
| 55 | +- Build/CI changes |
| 56 | + |
| 57 | +## How to update |
| 58 | + |
| 59 | +### Markdown conventions |
| 60 | + |
| 61 | +- Use Jekyll front matter (`---\nlayout: default\ntitle: ...\n---`) on every page |
| 62 | +- Use GitHub-Flavored Markdown (GFM) |
| 63 | +- Use fenced code blocks with language tags (`javascript`, `typescript`, `bash`) |
| 64 | +- Use Mermaid for flow/sequence/state diagrams (```mermaid blocks) |
| 65 | + |
| 66 | +### Diagrams |
| 67 | + |
| 68 | +- **ASCII trees** — Preferred for hierarchical/nested structures (stream structures, data models). They render everywhere, stay narrow, and are easy to edit. |
| 69 | +- **Mermaid** — Use for flowcharts, sequence diagrams, state machines. Rendered by GitHub and most Jekyll themes with mermaid support. |
| 70 | +- **Avoid inline SVG** — SVG does not render in most Markdown viewers (GitHub, Jekyll). Use ASCII or Mermaid instead. |
| 71 | +- Keep diagram source editable (no rasterized images for diagrams). |
| 72 | +- **Split complex diagrams** — When an architecture or overview diagram has multiple concerns (e.g., library modules + class relationships), split into separate graphs stacked vertically rather than one dense graph. This improves readability on all screen sizes. |
| 73 | + |
| 74 | +### Code examples |
| 75 | + |
| 76 | +- Every public method should have at least one usage example |
| 77 | +- Examples should be copy-pasteable and realistic |
| 78 | +- Use `const` and `await` consistently |
| 79 | +- Show typical output in comments where helpful |
| 80 | + |
| 81 | +### Adding a new page |
| 82 | + |
| 83 | +1. Create `docs/new-page.md` with Jekyll front matter |
| 84 | +2. Add entry to `nav:` in `docs/_config.yml` |
| 85 | +3. Add link to the table in `docs/index.md` |
| 86 | + |
| 87 | +## Publishing (gh-pages) |
| 88 | + |
| 89 | +The docs are designed for GitHub Pages with Jekyll. To publish: |
| 90 | + |
| 91 | +1. Enable GitHub Pages on the repo (Settings > Pages > Source: branch `main`, folder `/docs`) |
| 92 | +2. Jekyll will build automatically using the `_config.yml` configuration |
| 93 | +3. The Cayman theme is used via `remote_theme` |
| 94 | + |
| 95 | +For local preview: |
| 96 | + |
| 97 | +```bash |
| 98 | +cd docs |
| 99 | +gem install bundler jekyll |
| 100 | +bundle init |
| 101 | +# Add to Gemfile: gem "github-pages", group: :jekyll_plugins |
| 102 | +bundle install |
| 103 | +bundle exec jekyll serve |
| 104 | +``` |
| 105 | + |
| 106 | +## Versioning |
| 107 | + |
| 108 | +When the library version changes significantly, consider noting breaking changes at the top of affected pages. The docs track the current `main` branch — there is no versioned documentation (yet). |
| 109 | + |
| 110 | +## Checklist for doc PRs |
| 111 | + |
| 112 | +- [ ] Updated all affected pages |
| 113 | +- [ ] Code examples are correct and tested |
| 114 | +- [ ] Mermaid diagrams render (check on GitHub preview) |
| 115 | +- [ ] SVG diagrams are well-formed |
| 116 | +- [ ] `_config.yml` nav is up to date |
| 117 | +- [ ] `index.md` exports table is up to date |
| 118 | +- [ ] No broken internal links |
0 commit comments