Skip to navigation
For contributors

Maintaining the documentation

View as Markdown

The Fern repository publishes the documentation site. The WhizBoard UI and backend repositories are the evidence for product behavior. Update the feature page that owns the behavior and keep its code pointers current when implementation moves.

Update a feature guide

  1. Trace the user action from the UI route or component into its API adapter.
  2. Trace the API router into the controller, service, persistence model, and any external service it calls.
  3. Update the feature’s canonical page. Keep implementation status separate from provider, queue, or scheduler requirements.
  4. Add a navigation entry in fern/docs.yml only when adding a new page. Keep explicit frontmatter slugs stable; use redirects when retiring a published URL.
  5. Preview the site with fern docs dev, then validate it with fern check.

Update a diagram

Each feature diagram has an editable .excalidraw source and a same-name .svg image in fern/docs/assets/diagrams/. Open the source file from the repository in Excalidraw, make the change, export SVG to the matching path, and commit both files. The published feature page displays the SVG; the editable source stays in the repository. Keep labels concise and mark optional or external services on the diagram itself.

Update the API reference

The generated API reference reads fern/apis/whizboard/openapi.json. The repository workflow syncs that specification from the production API daily and after pushes to the default branch. To refresh it manually, run fern api update. Review the generated diff; a production OpenAPI document can lag a local feature change, so use the backend source for feature behavior and the API reference for the wire contract.

Page and diagram conventions

  • Keep one canonical feature page for each feature’s full explanation and availability status.
  • Link to the API reference for request and response details instead of copying schemas into feature prose.
  • Preserve the six Excalidraw source files in the repository. The SVG is the Fern-rendered export; the source file is the version maintainers can edit.
  • Check the preview at desktop and narrow widths, especially tables and diagrams.