CLAUDE - henk52/knowledgesharing GitHub Wiki

Documentation Guidelines

On changes, update relevant docs:

  • README.md - end-user guide (install, usage, troubleshooting, core make targets). Update when user-facing workflows change.
  • docs/DEVELOPMENT.md - maintainer guide. Update project structure tree, Where to Look table, improvement/review make targets, build instructions.
  • docs/ARCHITECTURE.md - system architecture reference. Update diagrams/tables when architecture changes.
  • docs/templates/ARCHITECTURE_template.md - template for ARCHITECTURE.md.
  • docs/templates/DEVELOPMENT_template.md - template for DEVELOPMENT.md.
  • docs/templates/generic_template.md - default template for other .md files.

Maintainers: DevOps, minimal JavaScript experience.

Style

  • No em-dash '—'.
  • No ASCII tree chars. Bullet lists only.
  • Table rows sorted alphabetically.
  • No ambiguous pronouns ('it', 'this', 'they') opening sentences. Restate subject.
  • H1 for title only. No heading deeper than H4.
  • Subsection of single parent item = one level lower than parent.
  • Numbered lists only when fenced code blocks sit between steps; else bullets.
  • Single commands inline as backticks. Fenced code blocks only for multi-line or when lang hint clarifies.

Topic structure

  • Self-contained topics. Each answers one question on one subject for one purpose.
  • Link to overviews for background.
  • Repeat context inside topic where needed for orientation.
  • Meaningful heading per topic.

Sentences + paragraphs

  • Short declarative/imperative sentences. Active voice, present tense, concrete words. Consistent terms.
  • One idea per paragraph. Topic sentence first. 3–5 sentences. ≤75 words.

Conciseness

  • No flowery language, buzzwords, unsupported claims.
  • No intro text that repeats headings.
  • Don't over-cut: avoid choppy/confusing/incomplete output.
  • For order-independent topics: link or repeat context as needed.
  • Prefer tables/charts/figures over prose where possible.
  • Prefer bullets over 2-column tables.

Headings

  • Short precise abstract of section content (headings show in search/bookmarks out of context).
  • No leading article or lowercase technical term.
  • Don't repeat parent heading text in subheadings.
  • Qualifiers (overview/task/reference) applied consistently if used.

Bullet lists

  • Break long paragraphs into bullets.
  • ≤9 items per list.
  • Concise phrases over full sentences.
  • Multi-sentence item: first sentence = summary.

Jump lists

  • Clickable topic list for navigation. Use for:
    • Chapter/section contents.
    • Procedures (inc. long complex tasks).
    • Related cross-referenced topics.
  • Briefly explain each link. Bold key terms.

Terminology

  • "authenticate" not "login".
  • "request" not "call".
  • Prefer "you" over "we".

Diagrams

  • Mermaid only.
  • Layout: outside = left, inside (described component) = right.