Contributing to ATOM Documentation

We welcome contributions to the ATOM Documentation repository! This guide will help you understand how to contribute effectively to AECOM's ATOM documentation site.

🚀 Getting started

Prerequisites

• .NET 8.0 SDK or later (for Nuke build system)
• DocFX CLI tool
• Git for version control
• Access to AECOM's GitHub Enterprise
• GitHub Personal Access Token (for cloning external repositories)

Development setup

1. Fork the repository on GitHub Enterprise
2. Clone your fork locally:

git clone https://github.com/AECOM-Enterprise/Atom-Doc.git
cd Atom-Doc

3. Set up GitHub token for accessing external repositories:

   The build system requires a GitHub Personal Access Token to clone private AtomCommon and AtomUI repositories.

Create a Personal Access Token:

1. Go to GitHub Enterprise > Settings > Developer settings > Personal access tokens
2. Generate a new token with repo scope
3. Copy the token value

Configure the token locally:

cd build
dotnet user-secrets set "GitHubToken" "your_personal_access_token_here"

Alternative: Environment variable (not recommended for security):

export GITHUB_TOKEN="your_personal_access_token_here"

4. Test the build system:

dotnet run --project "build/build.csproj" -- Clean

5. Build documentation to ensure everything works:

dotnet run --project "build/build.csproj" -- SimulateGitHubAction

🔄 Development workflow

The ATOM Documentation repository follows a standard GitHub workflow for documentation improvements.

Branch naming conventions

Choose the appropriate branch prefix based on your change type:

Documentation improvements:

• docs/fix-broken-links
• docs/improve-getting-started-guide
• docs/add-missing-examples

Build system changes:

• build/update-nuke-targets
• build/fix-docfx-configuration
• infra/improve-github-workflows

Template and styling:

• template/update-aecom-theme
• style/improve-navigation

Pull request process

1. Create a feature branch from main:

git checkout main
git pull origin main
git checkout -b docs/your-improvement-name

2. Make your changes following documentation standards:

• Update markdown files for content changes
• Modify DocFX configuration if needed
• Update build system targets if required

3. Test your changes locally:

# Or est individual components
dotnet run --project "build/build.csproj" -- BuildDocs

4. Verify the documentation renders correctly:

• Check generated site in docs/_site/
• Test navigation and links
• Verify API documentation is generated properly

5. Commit your changes with clear messages:

git add .
git commit -m "Fix broken links in contributing guide

- Update relative paths to use DocFX format
- Fix references to external repository content
- Improve navigation structure"

6. Push your branch and create a pull request:

git push origin docs/your-improvement-name

7. Create pull request on GitHub:

• Describe the documentation changes made
• Include screenshots of significant visual changes
• Request review from documentation maintainers

🆘 Getting help

• DocFX documentation - Official DocFX guides
• Nuke build documentation - Build system documentation
• AECOM code Wiki - AECOM development standards