Documentation Expectations

At EGI, documentation is a first-class deliverable. Well-maintained documentation reduces onboarding time, prevents knowledge silos, and ensures smooth handoffs to Anchor MSP for ongoing operations. Every team member is responsible for documenting their work.

What to Document

Code Documentation

All code written at EGI should be self-documenting where possible, supplemented by explicit documentation where intent is not obvious.

Type	Standard	When Required
Inline comments	Explain the "why," not the "what"	Complex logic, workarounds, non-obvious decisions
JSDoc / TSDoc	Function-level documentation with parameter and return types	Public APIs, utility functions, shared modules
README.md	Project overview, setup instructions, environment variables, deployment notes	Every repository must have one
CHANGELOG.md	Notable changes by version	Projects with external consumers or Anchor handoff

README Template (Minimum)

Every project README should include at minimum:

• Project name and one-line description
• Prerequisites (Node version, environment variables, external services)
• Setup instructions (clone, install, run)
• Deployment process (or link to deployment docs)
• Key architecture decisions or links to ADRs

Decision Documentation (ADRs)

Architecture Decision Records capture the reasoning behind significant technical choices. An ADR is required when:

• Choosing or changing a framework, library, or major dependency
• Designing a new system architecture or modifying an existing one
• Selecting an authentication or authorization strategy
• Making a decision that constrains future development options

ADR Format

# ADR-[number]: [Title]

## Status
Proposed | Accepted | Deprecated | Superseded

## Context
What is the problem or situation that requires a decision?

## Decision
What was decided and why?

## Consequences
What are the trade-offs? What becomes easier or harder?

ADRs are stored in the project repository under a /docs/adr/ directory or in the relevant SOP section if the decision is organization-wide.

Meeting Documentation

All meetings with actionable outcomes must be documented:

Meeting Type	Documentation Required	Where Stored
Sprint planning	Selected items, assignments, capacity notes	SuiteDash or project management tool
Retrospectives	What went well, what to improve, action items	SuiteDash or shared doc
Client meetings	Summary, decisions made, action items, follow-ups	SuiteDash client record
Technical discussions	Decision summary, ADR if applicable	Slack thread or ADR
1:1s	Action items only (not detailed notes)	Private to participants

Process Documentation

When a team member establishes or refines a process (deployment procedure, debugging workflow, integration setup), they are expected to document it in the appropriate SOP section or project wiki.

When to Document

Documentation should be created as close to the moment of the decision or implementation as possible. Retroactive documentation is significantly less accurate and more time-consuming.

Trigger	Expected Action
New feature merged	Update README if setup steps changed; add JSDoc to public interfaces
Architecture decision made	Write an ADR within 24 hours
New process established	Document in the relevant SOP section within the same sprint
Bug fix for non-obvious issue	Add an inline comment explaining the root cause and fix
Client meeting completed	Post meeting notes within 4 business hours
Sprint completed	Ensure all sprint-related documentation is up to date

Knowledge Base Contributions

EGI maintains internal documentation through this SOP system (built with Docusaurus). Every team member is expected to contribute:

• New hires: Submit at least one documentation improvement within their first 30 days (fixing an error, clarifying a procedure, adding missing information)
• All team members: Flag outdated documentation when encountered; either fix it or create an issue
• Subject matter experts: Own the accuracy of documentation in their domain

How to Contribute

1. Clone the SOP repository
2. Create a feature branch
3. Make your changes using Markdown
4. Submit a PR with a clear description of what was added or changed
5. Request review from the relevant team lead

Documentation Quality Standards

• Use clear, direct language; avoid jargon unless it is defined
• Structure content with headings, tables, and lists for scannability
• Include concrete examples where possible
• Keep content actionable: a reader should be able to follow the documentation and complete the task
• Date-stamp time-sensitive information
• Never include secrets, credentials, or internal IP addresses in documentation

Handoff Documentation

When a project is ready for Anchor MSP to manage, a handoff document must be prepared. See Documenting Auth for the authentication-specific handoff template. The general handoff document should cover:

• System architecture overview
• Deployment and hosting details
• Authentication and authorization model
• Monitoring and alerting configuration
• Known issues and technical debt
• Contact information for the original development team