Skip to main content

How to Update Documentation (Non-Technical Guide)

This guide provides step-by-step instructions for updating the Atlas documentation portal — designed for editors without technical or coding experience.

📋 Overview​

The Atlas documentation portal is powered by a system that combines auto-generated content with human-editable fragments. You can safely edit specific files to add descriptions, examples, and clarifications without breaking the automated system.

🛡️ Which Files Can I Edit?​

✅ Safe to Edit​

Files starting with an underscore (_) are safe to edit.

These are Markdown fragments that contain human-written content. Examples:

  • _nodeDescription.md
  • _nodeBehavior.md
  • _nodeEditorExample.md
  • _nodeUiTellus.md

Why? These files are preserved when the documentation generator runs. Your changes will not be overwritten.

❌ Do NOT Edit​

Files named index.mdx or other auto-generated files.

These files are created automatically by the documentation generator and will be completely overwritten the next time the generator runs.

⚠️ New Nodes, Subsections or Properties in Node Added to Your System?​

If new nodes, new subsections or properties in node have been added to Atlas system, the documentation scaffold must be regenerated:

  1. Contact the Claims Intake development team
  2. Ask them to run the documentation generation script to create new documentation folders for the new nodes or fragment files inside node folders
  3. Once they've run the generator, you can then edit the new _*.md fragment files to add descriptions and examples

This ensures all new nodes, subsections and properties in node have the proper documentation structure and are ready for your edits.

🔄 Workflow for Updating Documentation​

Step 1: Create a New Branch​

  1. Navigate to the Azure DevOps repository
  2. Click on Branches in the left sidebar
  3. Click the New branch button (top right)
  4. Fill in the form:
    • Name: Use a descriptive name like docs/update-message-node
    • Based on: Select main (or the default branch)
  5. Click Create

Your branch is now ready for editing!

Step 2: Edit Documentation Files​

Option A: Edit Existing Files

  1. Click on the branch name you just created
  2. Navigate to the file you want to edit
    • Example: ui/docs/node-types/Common/MessageNode/_nodeDescription.md
  3. Click the Edit button (pencil icon on top right)
  4. Make your changes in the editor
  5. Click Commit at the top right
  6. Add a brief commit message (e.g., "Update MessageNode description")
  7. Click Commit to save your changes

Option B: Create New Documentation Section

To add a new section or category to the documentation:

  1. Create a new folder in the appropriate location
    • Example: ui/docs/concepts/new-topic/
  2. Inside the folder, create a file named _category_.json with this content: 
    {
      "label": "Your Section Name",
      "position": 1,
      "description": "Brief description of what this section contains."
    }
  3. Create your documentation files in the same folder:
    • overview.md — Main introduction to your section

Adding Images and Links

Add an Image:

  1. Create an img/ folder in your documentation section
    • Example: ui/docs/node-types/Common/MessageNode/img/
  2. Upload your image file (PNG or SVG recommended)
    • Example: example-screenshot.png
  3. In your Markdown file, reference the image with: 
    ![Alt text describing the image](./img/example-screenshot.png)

Add a Link to Another Page:

Use this format to link to another documentation page:

[Link text](../../../path/to/page.md)

Or link to a specific section:

[Link text](../other-page.md#section-heading)

Examples:

# Link to a concept page
See the [Node Basics](../../concepts/node.md) guide for more information.

# Link to another node's documentation
For similar functionality, check [MessageNode](../MessageNode/_nodeDescription.md).

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

# Link to an image in your folder
![MessageNode example](./img/message-node-example.png)
  1. Click Commit to save all new files

💡 Tip: You can make multiple commits in the same branch! Just repeat the steps above for each file or change.

Step 3: Create a Pull Request (PR)​

Once you've made all your changes, you need to submit them for review.

  1. Navigate to Pull Requests in the left sidebar
  2. Click New pull request
  3. Fill in the form:
    • Title: Brief summary (e.g., "Update MessageNode documentation")
    • Description: Explain what you changed and why
  4. Click Create

Your pull request is now submitted for review!

Step 4: PR Review and Approval​

Who reviews PRs?

When you create a pull request, the Claims Intake development team automatically receives an alert. They will review your documentation changes to ensure:

  • Files are edited correctly (only _ prefixed files are modified)
  • Content is accurate and well-written
  • No auto-generated files were accidentally changed

What happens next?

  1. The Claims Intake team is notified of your PR
  2. A reviewer will check your changes
  3. They may leave comments or request modifications
  4. You can respond to comments and make additional commits to your branch
  5. Once approved, you can merge your PR into main by clicking Continue on top right
  6. Your changes will be automatically deployed to the documentation portal within a few minutes

🤖 AI Prompt for Documentation Editing​

Copy and paste this prompt into your AI assistant (ChatGPT, Copilot, Claude, etc.) to get help writing documentation:

You are helping me write documentation for the Atlas node-based flow editor.

**About the Editor:**
The Atlas editor is a node-based tool used to build conversational or form flows. Each "node" represents a discrete piece of UI or logic (for example: input fields, choices, data operations, summaries, or integrations). Nodes are connected together to create complete flows.

**Documentation Task:**
I need help writing clear, concise documentation for [NODE NAME or TOPIC]. 

**Guidelines:**
- Keep language simple and non-technical where possible
- Use examples to illustrate concepts
- Be factual and concise
- Follow this structure:
  - Description: What does this node/feature do?
  - Behavior: How does it work at runtime?
  - Configuration: What settings are available?
  - Examples: Show a real-world use case

**Target Audience:**
Documentation is for business users, developers, and technical writers working with the Atlas flow editor.

Please help me write [specific section, e.g., "a behavior description for the InputPhoneNode that explains validation and formatting rules"].

How to use this prompt:

  1. Copy the entire prompt above
  2. Paste it into your AI assistant
  3. Replace [NODE NAME or TOPIC] with your specific node or topic
  4. Replace [specific section] with what you need help with
  5. Review and refine the AI output before adding it to the documentation

✅ Quick Reference: Making Multiple Commits​

You can make multiple changes to your branch before creating a Pull Request:

  1. Edit a file and commit (Step 2 above)
  2. Edit another file and commit again
  3. Repeat as needed
  4. All commits stay in your branch until you create the PR

This allows you to organize your work in logical chunks and review changes before submitting.

📚 Additional Resources​

🆘 Need Help?​

If you encounter issues or have questions:

  • Check the project README for technical details
  • Ask your team's documentation owner
  • Contact the Atlas development team

Happy documenting! 🎉