Docs-as-Code
Treat architecture documentation like source code with version control, PR reviews, and CI/CD publishing. Core philosophy of NeoArc Studio.
Docs-as-Code treats documentation like source code: version controlled, reviewed, tested, and deployed. This is NeoArc's core philosophy. All content is stored as JSON files in Git, enabling the same workflows used for code.
Docs-as-Code Principles
NeoArc implements Docs-as-Code principles.
Version Control
All content is JSON files in Git
Plain Text
JSON format is diffable and mergeable
Same Tools
Same Git workflow as code
Review Process
Documentation changes in pull requests
Automation
CI/CD publishing pipelines
Single Source of Truth
One repository for code and documentation
Git Workflow for Architecture Docs
The feature branch workflow for architecture documentation.
File Format Benefits
NeoArc's JSON format provides key benefits for docs-as-code workflows.
| Benefit | Description |
|---|---|
| Diffable | JSON files show changes clearly in diffs |
| Mergeable | Standard Git merge for conflicts |
| Reviewable | Pull requests show diagram and documentation changes |
| Automatable | CI/CD can validate and publish |
| Portable | No vendor lock-in with standard JSON |
CI/CD Integration
NeoArc documentation can be integrated into CI/CD pipelines.
Docs-as-Code Practitioner Use Cases
Version Control Documentation
All content in Git as JSON
Review Documentation Changes
PR workflow with diff view
Automate Publishing
CI/CD pipeline integration
Single Source of Truth
Code and documentation in the same repository
Enable Offline Work
Desktop app with no SaaS dependency
Implementation Guidance
Offline and Air-Gapped Support
NeoArc's Docs-as-Code approach works in restricted environments.
| Feature | Description |
|---|---|
| Desktop application | No internet required for editing |
| Local publishing | Generate static sites locally |
| Git bundles | Transfer changes via USB or other offline methods |
| Self-hosted viewer | Deploy the viewer on internal infrastructure |
Next Steps
Branching Strategies for Documentation
Git branching patterns suited to architecture documentation.
Learn more →