M
Navigation
Getting StartedUpdated July 3, 2026

Contributing Overview

contributingdocumentationgetting-startedworkflowwriting-standardspublishingguide

Contributing overview

Welcome to the Epic on Azure MEGADOC documentation project! This overview provides a high-level introduction, project structure, and a quick start checklist for new contributors.

Quick start checklist

Use this checklist to get started contributing immediately:

Phase 1: Setup (10 minutes)

  • Review Project Structure
  • Set up Local Development
  • Understand GitHub Workflow

Phase 2: Content Creation (15 minutes)

  • Learn Writing Standards
  • Master Markdown Features
  • Practice Advanced Features

Phase 3: Publishing (5 minutes)

  • Follow Review approval process
  • Understand Deployment publishing

Understanding project structure

MEGADOC follows a clear, hierarchical structure that makes content easy to find and maintain.

docs/
├── index.md                 # Homepage
├── getting-started/         # Onboarding & basics
├── architecture/           # System design docs
├── guides/                # How-to guides
├── best-practices/        # Standards & patterns
├── operations/            # Day-to-day operations
├── security/              # Security guidelines
├── monitoring/            # Observability docs
├── infrastructure/        # IaC documentation
└── assets/               # Images & resources

File naming conventions

  • Use kebab-case: my-awesome-guide.md
  • Be descriptive: azure-vm-deployment.md
  • Include context: troubleshooting-login-issues.md
  • Avoid spaces: my-guide.md (not My Guide.md)

Asset organization

  • Images: docs/assets/images/section-name/
  • Diagrams: docs/assets/diagrams/
  • Downloads: docs/assets/downloads/

Working with submodules {#working-with-submodules}

MEGADOC aggregates ~74 git submodules. End-to-end guidance lives in dedicated pages — start there rather than duplicating instructions here:

  • Submodule Adder — tooling to register a new repo as a submodule.
  • Submodules Guide — adding, updating, troubleshooting, and the fallback system in .megadoc/.

Commit conventions

This repo enforces Conventional Commits on every branch commit via an org ruleset. Use only the canonical types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert. Invented prefixes such as security:, bug:, epic:, update:, or add: will be rejected.

For more details, see the other contributing guides: