# Writing and Maintaining Technical Documentation

Effective technical documentation is a critical component of maintainable software systems. Well-written documentation reduces onboarding time, minimizes support burden, and serves as a single source of truth for architectural decisions and implementation patterns.

## Documentation Philosophy

### Write for Your Audience

Technical documentation serves multiple audiences with different needs:

* New developers: Need conceptual overviews, getting started guides, and common patterns
* Experienced team members: Need detailed API references, edge cases, and optimization techniques
* Operations teams: Need runbooks, troubleshooting guides, and monitoring procedures
* Architects: Need system diagrams, integration patterns, and design decisions

Tailor content depth and terminology to your target audience. Avoid assuming knowledge that new team members won't have, but don't over-explain concepts that experienced developers already understand.

### Documentation as Code

Treat documentation with the same rigor as code:

* **Version control**: Store documentation in the same repository as code.
* **Review process**: Require peer review for documentation changes.
* **Broken link checking**: Validate internal and external references.
* **Search optimization**: Structure content for discoverability.

### Living Documentation

Documentation decays without maintenance:

* **Update on code changes**: Documentation updates are part of definition of done.
* **Regular reviews**: Schedule periodic audits to ensure accuracy.
* **Deprecation markers**: Clearly flag outdated content with removal dates.

## Style Guide Foundations

Follow [Google's Technical Writing Style Guide](https://developers.google.com/style) as your baseline, with the following Salesforce-specific adaptations.

### Terminology Standards

Maintain consistent terminology:

#### Salesforce-specific terms:

* Use "org" or "organization", not "instance" or "environment".
* Use "record" not "row" or "entry".
* Use "field" not "column" or "attribute".

#### Code element formatting:

* Class names: `AccountTriggerHandler`
* Method names: `processRecords()`
* Field names: `Account.AnnualRevenue`
* sObject API names: `Account`, `Opportunity`, `CustomObject__c`


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.goharrier.com/technical/technical-documentation/writing-technical-documentation.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.