Documentation System - Quick Reference Card

One-Page Cheat Sheet for Team Members

---

🎯 What Is It?

Automated documentation system that generates, indexes, and publishes docs from code comments across all repositories.

---

📊 System Overview

Code + Comments → DocFX Build → Elasticsearch + Azure → Browse/Search/Query

4 Layers:

1. Source - XML/JSDoc comments + Markdown articles
2. Build - DocFX generates static site
3. Distribution - Elasticsearch + Central Repo + Azure
4. Access - Web Browser + MCP + Search API

---

🔧 For Documentation Authors

C# - XML Comments

/// <summary>Brief description</summary>
/// <remarks>Detailed explanation with <a href="~/articles/my-article.md">links</a></remarks>
/// <param name="userId">Parameter description</param>
/// <returns>Return value description</returns>
/// <exception cref="NotFoundException">When thrown</exception>
public async Task<User> GetUser(string userId)

JavaScript - JSDoc Comments

/**
 * Brief description
 * @param {string} userId - Parameter description
 * @returns {Promise<User>} Return value description
 * @throws {NotFoundException} When thrown
 * @example
 * const user = await getUser('123');
 */
async function getUser(userId) { }

Markdown Articles

# Article Title
Brief intro with [API links](xref:Namespace.ClassName)

## Overview
High-level explanation

## Implementation
Code examples and details

---

🔍 For Documentation Consumers

1. Browse Documentation

URL: https://mango-forest-095ef9d03.3.azurestaticapps.net/

• Navigate API reference by namespace
• Read conceptual articles
• Use built-in search

2. Search from IDE (MCP)

@elasticsearch-jupiter How does IndexerService work?
@elasticsearch-jupiter Show me examples of comparable mapping

3. Query Elasticsearch Directly

Find all docs from a repo:

GET jupiter-documentation/_search
{
  "query": { "term": { "repository.keyword": "YourRepo" } },
  "size": 10
}

Full-text search:

GET jupiter-documentation/_search
{
  "query": {
    "multi_match": {
      "query": "your search terms",
      "fields": ["title^2", "content", "className"]
    }
  },
  "highlight": { "fields": { "content": {} } }
}

Filter by type:

GET jupiter-documentation/_search
{
  "query": {
    "bool": {
      "must": [{ "match": { "content": "search term" } }],
      "filter": [{ "term": { "type": "api" } }]
    }
  }
}

---

🚀 Adding a New Repository

Time: 2-3 hours initial setup

C# Repository Checklist

• Enable XML docs in .csproj: <GenerateDocumentationFile>true</GenerateDocumentationFile>
• Create docfx.json configuration
• Create index.md and toc.yml
• Create /docs folder with articles
• Copy azure-pipelines-docfx.yml
• Configure pipeline variables (ELASTIC_, CENTRAL_DOCS_)
• Test locally: docfx build docfx.json && docfx serve _site
• Push and verify pipeline runs

JavaScript Repository Checklist

• Install: npm install --save-dev jsdoc-to-markdown glob fs-extra
• Create scripts/generate-docs.js
• Create jsdoc.json configuration
• Update package.json with docs:generate script
• Create docfx.json configuration
• Create /docs folder with articles
• Copy azure-pipelines-docfx.yml (JavaScript version)
• Test locally: npm run docs:generate && docfx build docfx.json
• Push and verify pipeline runs

---

🛠️ Local Development

C# Projects

dotnet build                    # Build project
docfx metadata docfx.json       # Generate API metadata
docfx build docfx.json          # Build docs site
docfx serve _site               # Serve at http://localhost:8080

JavaScript Projects

npm run docs:generate           # Generate API docs from JSDoc
docfx build docfx.json          # Build docs site
docfx serve _site               # Serve at http://localhost:8080

---

📋 Pipeline Stages

All Branches:

• BuildDocumentation → Validates docs build successfully

Main Branch Only:

• BuildDocumentation → IndexToElastic → PublishToCentral
• Result: Docs live in ~5-10 minutes

---

🔑 Key Benefits

✅ Always Current - Generated from code on every merge
✅ Searchable - Full-text search across all repos
✅ IDE Integration - Query docs without leaving editor
✅ Automated - No manual doc generation
✅ Consistent - Same system across all repos

---

📞 Support & Resources

Documentation:

• Implementation Guide: docs/DOCUMENTATION_SYSTEM_GUIDE.md
• JavaScript Guide: presentation/JAVASCRIPT_INTEGRATION_GUIDE.md

External:

• DocFX: https://dotnet.github.io/docfx/
• XML Comments: https://learn.microsoft.com/en-us/dotnet/csharp/language-reference/xmldoc/
• JSDoc: https://jsdoc.app/

Help:

• Platform Team: [Contact Platform Team]
• Documentation Channel: [#jupiter-docs or team channel]

---

🎓 Best Practices

Writing Documentation

1. Document all public APIs - Classes, methods, properties
2. Include examples - Show real usage patterns
3. Link related docs - Cross-reference APIs and articles
4. Keep it current - Update docs with code changes
5. Use clear language - Write for your audience

Consuming Documentation

1. Start with articles - Get high-level understanding
2. Browse API reference - Explore class structure
3. Use search - Find specific information quickly
4. Try MCP queries - Natural language in your IDE
5. Bookmark frequently used - Save time

---

⚡ Quick Commands

Task	Command
Build C# docs locally	docfx build docfx.json
Build JS docs locally	npm run docs:generate
Serve docs locally	docfx serve _site
Count indexed docs	GET jupiter-documentation/_count
Search in IDE	@elasticsearch-jupiter [query]

---

Version: 1.0
Last Updated: 2025-11-28
Print this card for easy reference during development!