Central Documentation System

Technical Implementation

From Code to Published Documentation

1st December 2025

Agenda

System Overview
Technical Architecture
Implementation Flow
Live Demonstration
Developer Experience
Next Steps & Q&A

The Problem We Solved

Documentation Challenges

📚 Documentation scattered across repositories

🔍 Hard to find information

⏰ Often outdated or missing

🚫 No central knowledge base

💻 No IDE integration

Our Solution: Distributed Authoring, Centralized Publishing (Docusaurus)

1. SOURCE LAYER → Code Comments (XML/JSDoc) + Markdown Articles (in each repo)

2. EXPORT LAYER → Each source repo generates its own Markdown docs

3. AGGREGATION LAYER → Central repo imports docs from all source repos

4. BUILD LAYER → Docusaurus builds unified static site

5. DISTRIBUTION LAYER → Azure Static Web Apps + Central Repo + Elasticsearch

6. ACCESS LAYER → Web Browser + MCP + Search API

What We've Achieved

✅ 2 repositories integrated

Jupiter Market Elastic Comparables
Jupiter Market Elastic Titles

✅ Central documentation repository operational (Docusaurus)

✅ Elasticsearch index live (jupiter-documentation)

✅ Azure Static Web App deployed

✅ MCP server integration complete

✅ Local article search functionality

Layer 1: Where Documentation Lives

XML Comments (C#)

/// <summary>
/// Orchestrates the indexing pipeline
/// </summary>
/// <param name="dealId">The deal ID to index</param>
/// <returns>Success status</returns>
public async Task IndexDeal(Guid dealId)

Markdown Articles

docs/
├── introduction.md
├── getting-started.md
└── articles/
    └── indexer-logic.md

Layer 1: AI-Assisted Documentation

AI-Generated Conceptual Articles

🤖 Use AI tools to accelerate documentation:

Claude / ChatGPT / Copilot - Generate architecture overviews
Getting Started Guides - Create step-by-step tutorials
Best Practices - Document patterns and conventions
Tutorial Content - Build comprehensive learning materials

💡 Benefit: Quickly create high-quality conceptual documentation

Export, Aggregation, and Docusaurus Build

Source Code (C# or JS)
    ↓
Code Comments (XML/JSDoc) + Markdown articles
    ↓
Each repo generates Markdown docs (API + articles)
    ↓
Central repo imports all generated docs
    ↓ [Docusaurus Build]
Static HTML Site

Key Point: Each repo generates its own docs; central repo builds unified site

Layer 3: Azure DevOps Pipeline (Distributed Generation, Central Import & Build)

In each source repo:

GenerateDocs
- Build project
- Extract comments to Markdown (API + articles)
- Publish generated docs as artifact or push to shared location

In central docs repo: 2. ImportDocs

Download/copy generated docs from all source repos
Aggregate into /docs structure
Validate import

BuildDocumentation
- Build Docusaurus site (npm run build)
- Publish artifact
IndexToElastic (main only)
- Parse HTML/Markdown
- Index to Elasticsearch
PublishToCentral (main only)
- Deploy to Azure Static Web Apps

Result: Docs live in ~5-10 minutes

Layer 4: How Teams Consume Docs

🌐 Azure Static Web App (Docusaurus) Browse documentation, Built-in search, Professional UI

🔍 Elasticsearch Full-text search, API access, Rich metadata

📄 Local Article Search Client-side search, Fast filtering, No backend required

💻 MCP Server IDE integration, Natural language queries, Context-aware

Implementation Flow (Distributed Authoring, Central Import)

Developer writes code (in source repo)
    ↓
Adds code comments (XML/JSDoc) and Markdown articles
    ↓
Runs doc generation script/pipeline in source repo
    ↓
Commits code and generated docs to source repo or publishes as artifact
    ↓
Central repo imports/copies generated docs from all source repos
    ↓
Builds unified Docusaurus site (`npm run build`)
    ↓
Indexes docs to Elasticsearch
    ↓
Publishes site to Azure Static Web Apps
    ↓
Documentation available everywhere

Elasticsearch Document Structure

{
  "id": "jupiter-market-elastic-api-indexerservice",
  "repository": "Jupiter Market Elastic",
  "title": "IndexerService Class",
  "content": "Orchestrates the end-to-end indexing pipeline...",
  "type": "api",
  "namespace": "Jupiter.Market.Elastic.Services",
  "className": "IndexerService",
  "tags": ["indexing", "service", "pipeline"]
}

LIVE DEMONSTRATION

Azure Static Web App https://mango-forest-095ef9d03.3.azurestaticapps.net/

Elasticsearch Queries MCP Integration

Demo 1: Azure Static Web App

What to Show:

Homepage - Clean, professional landing page
Repository Selection - 3 integrated repositories
API Reference - Browse generated documentation
Articles Section - Conceptual documentation
Search Functionality - Built-in search + local article search
Cross-references - Links between docs

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

Demo 2: Elasticsearch Queries

Repository Filter:

GET jupiter-documentation/_search
{
  "query": {
    "term": { "repository.keyword": "Jupiter Market Elastic" }
  }
}

Full-Text Search:

GET jupiter-documentation/_search
{
  "query": {
    "multi_match": {
      "query": "IndexerService pipeline",
      "fields": ["title^2", "content", "className"]
    }
  }
}

Demo 3: MCP Integration

In VS Code/Cursor:

@elasticsearch-jupiter How does IndexerService work?

@elasticsearch-jupiter Show me examples of comparable mapping

Benefits:

Natural language queries
Context-aware responses
Direct links to documentation
No context switching

Developer Experience: Writing Docs

XML Comments:

/// <summary>Brief description</summary>
/// <remarks>Detailed explanation</remarks>
/// <param name="userId">Parameter description</param>
/// <returns>Return value description</returns>

Markdown Articles:

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

## Overview
High-level explanation

Developer Experience: Consuming Docs

Four Ways to Access:

Browse - Azure Static Web App Navigate, search, explore
Search - Elasticsearch queries Powerful filtering and aggregation
Local Search - Client-side article search Fast, instant filtering of documentation
Ask - MCP in IDE Natural language, instant answers

Key Benefit: Information at your fingertips

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 localhost:8080

JavaScript Projects:

npm run docs:generate           # Generate from JSDoc
docfx build docfx.json          # Build docs site
docfx serve _site               # Serve locally

Key Benefits: Developers

✅ Always up-to-date - Generated from code

✅ Easy to find - Search + IDE integration

✅ Clear examples - Code samples included

✅ Faster onboarding - Comprehensive guides

✅ Less context switching - Docs in IDE

Key Benefits: Teams

✅ Consistent - Same system across repos

✅ Centralized - One knowledge base

✅ Collaborative - Easy to contribute

✅ Discoverable - Search all projects

✅ Reduced silos - Shared knowledge

Key Benefits: Organization

✅ Automated - No manual doc generation

✅ Scalable - Works for any number of repos

✅ Low maintenance - Docs update with code

✅ Professional - High-quality output

✅ Cost-effective - Minimal infrastructure

Adding a New Repository

Time Estimate: 2-3 hours initial setup

Steps:

Enable XML documentation in .csproj
Create /docs structure
Add DocFX configuration
Write initial articles
Copy pipeline file
Configure variables
Test locally
Deploy

Multi-Language Support

C# Repositories:

XML Comments (///)
Custom extraction to Markdown
Namespace organization

JavaScript Repositories:

JSDoc Comments (/** */)
jsdoc-to-markdown
Markdown per file
File-based organization

Unified distribution layer (Docusaurus) for both!

Next Steps

Integrate Jupiter Frontend App
Train team on XML comments
Establish documentation standards
Create documentation templates
Gather feedback and iterate
Update to support cross-repo linking
Integrate AI into Azure Static Web App
Integrate into Nimbus ChatGPT environment

Technical Requirements

Prerequisites:

.NET 9.0 SDK
DocFX CLI tool
Azure DevOps access
Elasticsearch cluster access

Pipeline Variables:

ELASTIC_CLOUD_ID (secret)
ELASTIC_API_KEY (secret)
CENTRAL_DOCS_REPO
CENTRAL_DOCS_PAT (secret)

Success Metrics : Current

3 repositories integrated (Jupiter Market, Jupiter Market Elastic, Site Finding)
Documentation indexed and searchable in Elasticsearch
Azure Static Web App deployed at https://mango-forest-095ef9d03.3.azurestaticapps.net/
Local article search functionality implemented
MCP integration working with Elasticsearch

Success Metrics : Future

Documentation coverage %
Search query volume
Developer satisfaction
Time to find information

Resources & Support

Documentation:

Implementation Guide: docs/DOCUMENTATION_SYSTEM_GUIDE.md
JavaScript Guide: presentation/JAVASCRIPT_INTEGRATION_GUIDE.md
Quick Reference: presentation/QUICK_REFERENCE_CARD.md

External:

Docusaurus: https://docusaurus.io/
XML Comments: https://learn.microsoft.com/dotnet/csharp/xmldoc/
JSDoc: https://jsdoc.app/

Common Questions

Q: How long to integrate a new repo? A: 2-3 hours initial setup

Q: Do we document everything? A: Focus on public APIs and key concepts

Q: What about versioning? A: Single version now, can add if needed

Q: How much does it cost? A: Minimal - free tier + existing infrastructure

Questions?

Platform Team Documentation: presentation/DOCUMENTATION_SYSTEM_PRESENTATION.md

Thank you!

Backup Slides

Pipeline YAML Structure

trigger:
  branches: [main, develop]

stages:
  - BuildDocumentation (all branches)
  - IndexToElastic (main only)
  - PublishToCentral (main only)

Each stage:

Runs in isolated environment
Has specific dependencies
Publishes artifacts for next stage

Elasticsearch Index Mapping

Key Fields:

repository - Source repository name
type - "api" or "article"
namespace - C# namespace
className - Class name
content - Full text content
title - Document title
url - Relative URL path
tags - Categorization tags

JSDoc Example

/**
 * User authentication service
 * @param {string} email - User email
 * @param {string} password - User password
 * @returns {Promise<AuthToken>} Authentication token
 * @throws {AuthenticationError} When credentials invalid
 * @example
 * const token = await login('user@example.com', 'password');
 */
async function login(email, password) {
  // Implementation
}

<!--
Backup slide: JSDoc example showing how to document JavaScript functions with parameters, return types, exceptions, and usage examples.
-->

Technical Implementation​