How to Update Documentation (Technical Guide)

This guide provides step-by-step instructions for developers and technical contributors updating the Atlas documentation system — covering automated generation, Git workflows, and code-integrated changes.

📋 Overview

The Atlas documentation system is built on two core concepts:

Auto-Generated Content — Node documentation is automatically created from node models via the .NET generator (generator/AtlasNodeDocGenerator)
Human-Editable Fragments — Markdown files starting with _ are safe to edit and won't be overwritten during generation

This hybrid approach ensures documentation stays in sync with code while allowing flexible customization.

🛡️ File Safety Rules

✅ Safe to Edit

Files starting with underscore (_):

_nodeDescription.md
_nodeBehavior.md
_nodeEditorExample.md
_nodeUiTellus.md
Any other _*.md files

These fragments are preserved during generation and tracked in Git..

❌ Do NOT Edit

Auto-generated files (regenerated on every run):

index.mdx — Main aggregated documentation page
Generated metadata and structure files

These files are overwritten when the documentation generator runs, making any manual edits pointless.

Reference: See the project README for details on the generator architecture.

⚠️ New Nodes Added to Your System?

If new nodes have been added to Atlas system, run the documentation generation script to scaffold documentation folders:

cd generator
dotnet run --project AtlasNodeDocGenerator/AtlasNodeDocGenerator.csproj

This will:

Scan all registered nodes from the NuGet package
Create new documentation folders for any new nodes
Generate scaffold _*.md fragment files ready for editing
Create index.mdx files that compose all fragments

After generation:

Review the newly created folders in ui/docs/node-types/
Edit the new _*.md fragment files to add descriptions, examples, and platform-specific notes

🔄 Documentation Workflow

Step 1: Create a Feature Branch

git checkout -b docs/your-feature-description

Or via Azure DevOps portal:

Navigate to Branches
Click New branch
Enter branch name (e.g., docs/add-messagenode-examples)
Click Create

Step 2: Edit Fragment Files

Edit any _*.md files in your node documentation directory:

ui/docs/node-types/Common/MessageNode/
├── _nodeDescription.md      ✅ Edit this
├── _nodeBehavior.md         ✅ Edit this
├── _nodeEditorExample.md    ✅ Edit this
├── _nodeUiTellus.md         ✅ Edit this
├── img/                      └─ Images folder
│   └── screenshot.png
└── index.mdx                ❌ Don't edit

Example workflow:

# Edit a fragment file
nano ui/docs/node-types/Common/MessageNode/_nodeBehavior.md

# Stage and commit
git add ui/docs/node-types/Common/MessageNode/_nodeBehavior.md
git commit -m "docs: Add validation details to MessageNode behavior"

Adding Images and Links

Include an Image:

Create an img/ folder in your documentation section
Add image files (PNG or SVG recommended)

Reference in Markdown:

![Alt text](./img/example-screenshot.png)

Link to Other Pages:

# Link to related documentation
See the [Node Basics](../../concepts/node.md) guide.

# Link to another node
Check [MessageNode](../MessageNode/_nodeDescription.md).

# Link to specific section with anchor
Learn about [validation](../MessageNode/_nodeBehavior.md#validation).

Creating New Documentation Sections

To add a new documentation category or section:

Create a folder structure:
```
ui/docs/your-category/your-section/
```

Create _category_.json:

{
  "label": "Section Name",
  "position": 1,
  "description": "Brief description of this section."
}

Create documentation files in the folder:
- overview.md — Main page
- img/ — Optional images subfolder

Commit and push:

git add ui/docs/your-category/
git commit -m "docs: Add new section - Your Section"

Step 3: Run the Documentation Generator (Optional)

If you've added or modified node properties in your code, regenerate documentation:

cd generator
dotnet run --project AtlasNodeDocGenerator/AtlasNodeDocGenerator.csproj

What this does:

Scans all nodes from the NodeRegistry
Creates new fragment files for any new properties
Regenerates index.mdx files
Preserves all existing _*.md files

Commit the generated files:

git add ui/docs/node-types/
git commit -m "chore: Regenerate documentation after adding node properties"

Step 4: Make Multiple Commits

Organize your work into logical commits:

# Commit 1: Add description
git commit -m "docs: Add MessageNode description"

# Commit 2: Add behavior details
git commit -m "docs: Update MessageNode behavior documentation"

# Commit 3: Add examples
git commit -m "docs: Add MessageNode configuration examples"

# View your commits
git log --oneline -3

Step 5: Create a Pull Request

Via command line:

git push origin docs/your-feature-description

Then create the PR in Azure DevOps:

Navigate to Pull Requests
Click New pull request
Set:
- Source branch: docs/your-feature-description
- Target branch: main
- Title: Clear, concise title (e.g., "docs: Enhance MessageNode documentation")
- Description: Explain changes, link any related issues
Click Create

Step 6: PR Review and Merge

Who reviews?

The Claims Intake development team is automatically notified when you create a PR. Reviewers will:

Verify only _*.md files are modified (or regenerated index.mdx files)
Check documentation accuracy and alignment with node behavior
Review code samples and examples for clarity
Ensure no breaking changes to fragment structure

Review cycle:

Team is notified via PR alert
Reviewers may request changes or add comments
You can push additional commits to address feedback
Once approved, you can merge the PR
Changes deploy to the documentation portal within minutes

🔧 Working with the Generator

Understanding Fragment Generation

When the generator runs, it:

Scans node properties from the NuGet package (If.ClaimsIntake.Atlas.Models)
Creates sections for each property (inputs, outputs, validation rules, etc.)
Generates _fragments.md files as placeholders
Builds index.mdx by composing all fragments
Skips existing content — never overwrites _*.md files

Example: Adding Properties to a Node

If you add a new property to SendDataNode in the C# code:

public class SendDataNode : Node
{
    public ProvidedInputVariable AttachmentsConsent { get; } = new ProvidedInputVariable("AttachmentsConsent");
    public ProvidedInputBooleanVariable ManualHandlingRequired { get; } = new ProvidedInputBooleanVariable("ManualHandlingRequired");
    public ProvidedInputVariable AdditionalInternalMessage { get; } = new ProvidedInputVariable("AdditionalInternalMessage"); -- new property

}

After running the generator:

A new _additionalInternalMessage_input.md fragment is created
You can edit this fragment to add details
The index.mdx will include the new property automatically

🤖 AI-Assisted Documentation

The project includes a Copilot Instructions file that provides structured context for AI-assisted documentation:

File: .github/copilot-instructions.md
Purpose: Defines editor context, node structure, documentation conventions, and best practices
Automatic Context: GitHub Copilot and other AI tools automatically pick up this file as context when working in this repository

How to use:

When using AI tools (GitHub Copilot, ChatGPT, Claude, etc.) to help write documentation:

The AI will automatically have access to the conventions in copilot-instructions.md
No need to manually copy/paste the file — just ask for documentation help normally
The AI will understand the editor context and produce consistent, well-structured documentation
Reference the file directly if you want to emphasize specific conventions: "See .github/copilot-instructions.md for structure details"

✅ Checklist for Documentation PRs

Before submitting your PR:

Only _*.md files are modified (or regenerated index.mdx files)
No changes to index.mdx unless you ran the generator
Commit messages follow convention: docs: or chore: prefix
Documentation is clear and uses examples
No broken links or references
Changes align with the copilot instructions (structure, tone, examples)
If you regenerated docs, include the generator commit
Images are in img/ folder with relative paths

📚 Additional Resources

Project README — Architecture and setup instructions

🆘 Troubleshooting

Fragments Not Appearing in Documentation

Check that:

Fragment files are named correctly (_*.md)
Fragment is in the correct node folder
index.mdx exists and references the fragment
Documentation portal is rebuilt (automatic on main branch)

PR Merge Conflicts

If index.mdx files conflict:

# Regenerate conflicting files
dotnet run --project generator

# Commit the regenerated versions
git add ui/docs/node-types/
git commit -m "chore: Resolve merge conflicts in generated documentation"
git push

📝 Development Workflow Tips

Sync before starting:

git fetch origin
git checkout main
git pull origin main

Keep your branch updated:

git rebase main
# or
git merge main

Review your changes before committing:

git diff
git status

View documentation locally (requires Node.js setup):

cd ui
npm install
npm run start

Happy documenting! 🎉

📋 Overview​

🛡️ File Safety Rules​

✅ Safe to Edit​

❌ Do NOT Edit​

⚠️ New Nodes Added to Your System?​

🔄 Documentation Workflow​

Step 1: Create a Feature Branch​

Step 2: Edit Fragment Files​

Step 3: Run the Documentation Generator (Optional)​

Step 4: Make Multiple Commits​

Step 5: Create a Pull Request​

Step 6: PR Review and Merge​

🔧 Working with the Generator​

Understanding Fragment Generation​

Example: Adding Properties to a Node​

🤖 AI-Assisted Documentation​

✅ Checklist for Documentation PRs​

📚 Additional Resources​

🆘 Troubleshooting​

Fragments Not Appearing in Documentation​

PR Merge Conflicts​

📝 Development Workflow Tips​