Skip to main content

Collect source material

Strong docs updates start with strong inputs. Before writing or refreshing pages, gather the source material that anchors the repo in reality.

Files to inspect first​

Open the repo itself and start with the files most likely to contain stable truth:

  • README.md
  • docs/ and docs/runbooks/
  • example READMEs
  • Makefile, package.json, pyproject.toml, go.mod, or other build metadata
  • local run scripts such as docker-compose.yml, Dockerfile, or dev helpers
  • the main runtime entrypoints, such as cmd/..., src/main..., or package roots
  • deployment or environment configuration paths when the docs need operational setup details

What to capture in your notes​

Capture concrete answers for:

  • repo name and workspace path
  • one-sentence repo purpose
  • key entrypoints and important directories
  • setup, run, test, build, and verification commands
  • important source docs and runbooks
  • examples worth linking from the hosted docs
  • diagrams or architecture notes that should be preserved
  • Bitbucket URL and any repo-specific links that belong in the docs UI
  • owner or steward if the repo has a clearly documented one

Resolve conflicts deliberately​

When two sources disagree, trust them in this order:

  1. commands that currently run in the repo
  2. code and runtime entrypoints
  3. repo-local runbooks and maintained docs
  4. older summary pages in docs_ui

If you still cannot tell which source is right, document the unknown instead of hiding it.

Keep the evidence small and reviewable​

Avoid giant dumps of every markdown file in the repo. The best maintainer notes are short and specific:

  • README.md covers local setup
  • docs/runbooks/release.md is the best deploy reference
  • cmd/notify-sender/main.go is the runtime entrypoint
  • make test-integration is the safest end-to-end check

Next steps​