Documentation & ADRs - Archyl Docs

Create and manage architecture documentation and Architecture Decision Records in Archyl

Documentation & ADRs

Archyl provides powerful documentation features that let you create rich, linked documentation alongside your architecture diagrams. Keep your architectural knowledge organized and connected.

Creating Documentation

Manual Documentation

To create documentation manually:

  1. Go to the Docs tab in your project
  2. Click New Doc
  3. Enter a title and write your content in Markdown
  4. Add tags for organization
  5. Click Save

Documentation supports full Markdown syntax including:

  • Headings and formatting
  • Code blocks with syntax highlighting
  • Tables and lists
  • Images and links

Importing from Git

You can import existing documentation from your Git repository:

  1. Go to Project Settings > Documentation Discovery
  2. Configure your repository connection
  3. Click Discover Docs
  4. Review and approve discovered documentation

This is perfect for importing existing README files, technical specs, or wiki content.

Linking to Architecture Elements

Documentation becomes more powerful when linked to your architecture:

Creating Links

  1. Open a documentation page
  2. Click Link to Element
  3. Search or browse for the architecture element
  4. Select the element(s) to link
  5. Click Done

Viewing Linked Documentation

When viewing an element in the diagram, linked documentation appears in the details panel. This provides instant context without leaving the diagram view.

Use Cases for Linking

  • Link API documentation to Service containers
  • Link setup guides to infrastructure components
  • Link design specs to system contexts
  • Link code comments to Code elements

Architecture Decision Records (ADRs)

ADRs document important architectural decisions with their context and consequences.

What is an ADR?

An Architecture Decision Record captures:

Field Description
Title What was decided
Status Proposed, Accepted, Deprecated, or Superseded
Context Why this decision was needed
Decision What was decided
Consequences Impact of the decision

Creating an ADR

  1. Go to the Decisions tab in your project
  2. Click New ADR
  3. Fill in the ADR fields
  4. Link to relevant architecture elements
  5. Click Save

ADR Workflow

ADRs follow a lifecycle:

  1. Proposed: Initial draft, under discussion
  2. Accepted: Decision has been made and approved
  3. Deprecated: No longer relevant but kept for history
  4. Superseded: Replaced by a newer decision

ADR Discovery

Like documentation, ADRs can be discovered from your repository:

  1. Go to Project Settings > ADR Discovery
  2. Configure the path to your ADRs (e.g., docs/adr/)
  3. Click Discover ADRs
  4. Review and approve discovered records

Best Practices

Keep Documentation Current

  • Update docs when architecture changes
  • Review documentation during sprint retrospectives
  • Use ADRs for significant decisions

Link Everything

  • Every system should have a description doc
  • Link ADRs to affected components
  • Cross-reference related documentation

Use Tags Effectively

  • Tag by domain (auth, payments, etc.)
  • Tag by type (api, guide, spec)
  • Tag by status (draft, review, final)

ADR Guidelines

  • Create ADRs for significant decisions
  • Include alternatives considered
  • Document the trade-offs
  • Link to implementation PRs when possible

Documentation Discovery Settings

Configure how documentation is discovered:

Path Patterns

Specify which paths to scan:

docs/
wiki/
README.md
*.md

Exclude Patterns

Skip certain files:

node_modules/
vendor/
CHANGELOG.md

Next Steps