Table of Contents

Documentation standards

Clear and comprehensive documentation is essential for making ATOMCommon understandable, maintainable, and usable across AECOM's engineering teams.

📝 Documentation philosophy

ATOMCommon follows a multi-layered documentation approach:

  • Code documentation - XML comments for API reference
  • Conceptual documentation - High-level guides and tutorials
  • Process documentation - Development and contribution workflows
  • Architecture documentation - System design and structure

Framework baseline

  • Target framework: .NET 8 (net8.0) only
  • Tests: CI builds and runs unit tests on .NET 8
  • Examples and API docs assume .NET 8

🔧 XML documentation comments

All public APIs must include comprehensive XML documentation comments following C# standards.

Required elements

Classes and interfaces:

/// <summary>
/// Represents a horizontal alignment for road and infrastructure design.
/// Provides functionality for creating, manipulating, and analyzing geometric elements.
/// </summary>
/// <remarks>
/// This class supports various geometric elements including tangents, arcs, and spirals.
/// All calculations follow AASHTO geometric design standards.
/// </remarks>
public class Alignment

Methods:

/// <summary>
/// Converts a length value from one unit to another using the UnitsNet library.
/// </summary>
/// <param name="value">The numeric value to convert</param>
/// <param name="fromUnit">The source unit type</param>
/// <param name="toUnit">The target unit type</param>
/// <returns>The converted value in the target unit</returns>
/// <exception cref="ArgumentException">Thrown when invalid unit types are provided</exception>
/// <example>
/// <code>
/// var meters = Units.ConvertLength(100, UnitType.Feet, UnitType.Meters);
/// // Result: 30.48 meters
/// </code>
/// </example>
public static double ConvertLength(double value, UnitType fromUnit, UnitType toUnit)

Properties:

/// <summary>
/// Gets or sets the horizontal elements that define the alignment geometry.
/// </summary>
/// <value>
/// A list of <see cref="HorizontalEntity"/> objects representing the geometric elements.
/// </value>
/// <remarks>
/// Elements are ordered sequentially along the alignment. Each element must connect
/// properly with adjacent elements to maintain geometric continuity.
/// </remarks>
public List<HorizontalEntity> HorizontalElements { get; set; }

Best practices

  • Be descriptive: Explain what, why, and how - not just what the code does
  • Include examples: Provide practical usage examples for complex methods
  • Document parameters: Explain parameter meaning, constraints, and expected formats
  • Note exceptions: Document when and why exceptions are thrown
  • Link related items: Use <see cref=""/> to reference related types and members
  • Explain units: Always specify units for engineering calculations
  • Include remarks: Add context about usage patterns, performance, or limitations

📚 Conceptual documentation

Structure

Conceptual documentation is organized in the docs/ folder:

docs/
├── index.md                    # Main landing page
├── docs/
│   ├── contributing.md        # How to contribute
│   └── documentation.md       # This file
└── api/                        # Auto-generated API docs

Writing guidelines

Use clear headings:

  • Use descriptive, action-oriented headings
  • Follow consistent hierarchy (H1 → H2 → H3)
  • Include emoji icons for visual hierarchy when appropriate

Provide practical examples:

## Basic usage

Create a horizontal alignment for a highway design:

```csharp
var alignment = new Alignment();
var tangent = new Tangent(startPoint, endPoint, 1000.0);
alignment.HorizontalElements.Add(tangent);


**Link to related content:**
- Reference API documentation: `[Alignment class](xref:ATOM.Civil.Alignment)`
- Reference external resources: `[AASHTO standards](https://www.transportation.org/)`

## 🚀 DocFX integration

ATOMCommon uses DocFX for automated documentation generation and deployment.

### Configuration
Documentation is configured in `docs/docfx.json`:
- **Metadata extraction** from XML comments
- **Conceptual content** from markdown files  
- **Custom templates** for AECOM branding
- **Cross-references** between API and conceptual docs

### Automatic deployment
- Documentation builds automatically on push to main branch
- Deployed to Azure Static Web Apps at [atomcommon.aecom.software](https://atomcommon.aecom.software)
- API reference updates with each release

## ✅ Quality standards

### Review checklist
Before submitting documentation changes:

- [ ] All public APIs have XML documentation
- [ ] Examples compile and run correctly
- [ ] Links work and point to correct targets
- [ ] Spelling and grammar are correct
- [ ] Content follows AECOM style guidelines
- [ ] Code examples use realistic engineering scenarios
- [ ] Units are clearly specified for all engineering values

### Style guidelines

**Technical writing:**
- Use active voice where possible
- Write concisely but completely
- Define technical terms on first use
- Use consistent terminology throughout

**Code examples:**
- Use realistic engineering values and scenarios
- Include complete, compilable examples when possible
- Follow established C# coding conventions
- Comment complex calculations and formulas

**Engineering context:**
- Reference relevant industry standards (AASHTO, ACI, etc.)
- Explain engineering significance of calculations
- Include typical value ranges and constraints
- Mention real-world applications and use cases

## 🔗 Additional resources

- [AECOM C# Style Guide](https://codewiki.aecom.software/docs/code-guides/csharp-guide)
- [DocFX Documentation](https://dotnet.github.io/docfx/)
- [XML Documentation Comments Guide](https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/)
- [Markdown Syntax Reference](https://commonmark.org/help/)

Good documentation is a key part of the ATOMCommon ecosystem - it enables effective collaboration and ensures the library can serve AECOM's engineering teams effectively.