Documentation System - Live Demo Script

This script provides step-by-step instructions for conducting the live demonstrations during the presentation.

---

Pre-Demo Checklist

Before the Presentation

• Verify Azure Static Web App is accessible
• Test Elasticsearch cluster connectivity
• Confirm MCP server is configured in IDE
• Prepare backup screenshots for each demo
• Clear browser cache and history
• Close unnecessary browser tabs
• Set browser zoom to 100%
• Test screen sharing quality

URLs to Have Ready

• Azure Static Web App: https://[your-app-name].azurestaticapps.net
• Kibana Dev Tools: https://[your-kibana-url]/app/dev_tools#/console
• Central Docs Repo: https://dev.azure.com/[org]/[project]/_git/[repo]

Tools to Have Open

1. Browser with Azure Static Web App
2. Kibana Dev Tools (or alternative Elasticsearch client)
3. VS Code/Cursor with MCP configured
4. Azure DevOps pipeline page

---

Demo 1: Azure Static Web App (5 minutes)

Objective

Show the complete documentation website with navigation, API reference, articles, and search functionality.

Step-by-Step Script

1.1 Homepage (30 seconds)

Action: Navigate to homepage
URL: https://[your-app-name].azurestaticapps.net

Say:

"This is our central documentation site, automatically generated from code and deployed to Azure Static Web Apps. Let me show you what's available."

Point Out:

• Clean, professional design
• Main navigation menu
• Quick links section
• Search box in header

---

1.2 API Reference Navigation (1 minute)

Action: Click "API Documentation" in navigation

Say:

"The API Reference section contains all our code documentation, automatically extracted from XML comments."

Navigate:

1. Click on a namespace (e.g., Jupiter.Market.Elastic.Services)
2. Show the namespace overview page
3. Point out the list of classes

Point Out:

• Hierarchical namespace structure
• All public classes listed
• Brief descriptions from XML comments

---

1.3 Class Documentation (1.5 minutes)

Action: Click on IndexerService class

Say:

"Here's a detailed view of the IndexerService class. Notice how the XML comments we write in code become rich documentation."

Scroll Through and Point Out:

• Class summary and remarks
• Link to conceptual article (click it to show cross-reference)
• Constructor documentation
• Method list with summaries
• Parameter descriptions
• Return value documentation
• Exception documentation
• See Also section with related classes

Key Point:

"All of this is generated automatically from our code. When we update XML comments, the docs update automatically."

---

1.4 Articles Section (1 minute)

Action: Navigate to Articles section

Say:

"Beyond API reference, we have conceptual articles that explain how things work."

Navigate:

1. Click "Articles" in main navigation
2. Open "IndexerService Logic" article

Point Out:

• Clear structure (Overview, Key Concepts, Implementation)
• Code examples with syntax highlighting
• Links to related API documentation
• Links to other articles
• Diagrams (if present)

Demonstrate Cross-Reference:

• Click a link to API documentation
• Show how it navigates to the class
• Click back to article

---

1.5 Search Functionality (1 minute)

Action: Use the search box

Say:

"The site has built-in search powered by DocFX."

Search Examples:

1. Type "IndexerService" → Show instant results
2. Type "deal processing" → Show article results
3. Click a result → Navigate to documentation

Point Out:

• Instant search results
• Results from both API and articles
• Highlighted matches
• Direct navigation

---

Demo 1 Backup Plan

If Azure Static Web App is down:

• Use local DocFX serve (http://localhost:8080)
• Show screenshots from presentation
• Explain what would be visible

---

Demo 2: Elasticsearch Index (3 minutes)

Objective

Demonstrate how documentation is indexed and searchable via Elasticsearch API.

Step-by-Step Script

2.1 Index Overview (30 seconds)

Action: Open Kibana Dev Tools

Say:

"All our documentation is indexed in Elasticsearch, making it searchable across all repositories."

Run Query:

GET jupiter-documentation/_count

Point Out:

• Total number of indexed documents
• Single index for all repositories

---

2.2 Repository Filter (45 seconds)

Action: Query documents from specific repository

Say:

"Let's see all documents from the Comparables repository."

Run Query:

GET jupiter-documentation/_search
{
  "query": {
    "term": {
      "repository.keyword": "Jupiter.Market.Elastic.Comparables"
    }
  },
  "size": 5,
  "_source": ["title", "type", "url", "repository"]
}

Point Out:

• Repository field for filtering
• Document types (api, article)
• URLs for navigation
• Metadata structure

---

2.3 Full-Text Search (1 minute)

Action: Perform full-text search

Say:

"Now let's search for content about IndexerService across all documentation."

Run Query:

GET jupiter-documentation/_search
{
  "query": {
    "multi_match": {
      "query": "IndexerService pipeline orchestration",
      "fields": ["title^2", "content", "className"]
    }
  },
  "highlight": {
    "fields": {
      "content": {
        "fragment_size": 150,
        "number_of_fragments": 3
      }
    }
  },
  "size": 3
}

Point Out:

• Multi-field search (title, content, className)
• Title boosting (^2)
• Highlighted matches in results
• Relevance scoring

---

2.4 Filtered Search (45 seconds)

Action: Search with filters

Say:

"We can combine search with filters to find specific types of documentation."

Run Query:

GET jupiter-documentation/_search
{
  "query": {
    "bool": {
      "must": [
        { "match": { "content": "data service" } }
      ],
      "filter": [
        { "term": { "type": "api" } },
        { "term": { "repository.keyword": "Jupiter.Market.Elastic.Comparables" } }
      ]
    }
  },
  "size": 3,
  "_source": ["title", "namespace", "className", "url"]
}

Point Out:

• Boolean queries
• Filters (type, repository)
• Structured results
• Namespace and class information

---

Demo 2 Backup Plan

If Elasticsearch is unavailable:

• Show pre-captured query results
• Explain the query structure
• Show example JSON responses

---

Demo 3: MCP Server Integration (2 minutes)

Objective

Show how developers can query documentation directly from their IDE using natural language.

Step-by-Step Script

3.1 Setup (15 seconds)

Action: Open VS Code/Cursor with MCP configured

Say:

"With MCP integration, developers can query documentation without leaving their IDE."

Show:

• Copilot chat panel open
• MCP server connected (show status)

---

3.2 Natural Language Query (45 seconds)

Action: Query using MCP tool

Say:

"Let's ask a question about how IndexerService works."

Type in Chat:

@elasticsearch-jupiter How does IndexerService orchestrate the indexing pipeline?

Wait for Response

Point Out:

• Natural language query
• MCP server processes request
• Searches Elasticsearch
• Returns relevant documentation
• Highlighted matches
• Links to full documentation

---

3.3 Follow-up Query (30 seconds)

Action: Ask a more specific question

Say:

"We can ask follow-up questions to drill down."

Type in Chat:

@elasticsearch-jupiter What does DataService do?

Point Out:

• Context-aware responses
• Multiple document results
• Code examples in results
• Direct links to API reference

---

3.4 Code Example Query (30 seconds)

Action: Request code examples

Say:

"We can even ask for specific examples."

Type in Chat:

@elasticsearch-jupiter Show me examples of comparable mapping

Point Out:

• Finds relevant articles
• Returns code snippets
• Provides context
• Links to full documentation

---

Demo 3 Backup Plan

If MCP is not working:

• Show screenshots of successful queries
• Demonstrate manual Elasticsearch query
• Explain the expected behavior

---

Demo 4: Pipeline Execution (Optional - 2 minutes)

Objective

Show the automated pipeline that builds and deploys documentation.

Step-by-Step Script

4.1 Pipeline Overview (30 seconds)

Action: Navigate to Azure DevOps pipeline

Say:

"Every time we merge to main, this pipeline automatically builds and deploys our documentation."

Show:

• Recent pipeline runs
• Success/failure status
• Execution time

---

4.2 Pipeline Stages (1 minute)

Action: Click into a successful run

Say:

"The pipeline has three stages that run sequentially."

Point Out Each Stage:

1. BuildDocumentation

   • Builds .NET project
   • Generates XML documentation
   • Runs DocFX
   • Creates static site

2. IndexToElastic

   • Downloads build artifact
   • Runs PowerShell script
   • Indexes to Elasticsearch

3. PublishToCentral

   • Pushes to central repository
   • Deploys to Azure

---

4.3 Build Logs (30 seconds)

Action: Open BuildDocumentation stage logs

Say:

"We can see exactly what happened during the build."

Scroll Through Logs:

• DocFX metadata generation
• DocFX build output
• Number of files generated
• Any warnings or errors

---

Demo 4 Backup Plan

If pipeline access is restricted:

• Show pipeline YAML file
• Explain each stage
• Show example logs from screenshot

---

Post-Demo Talking Points

Key Takeaways to Emphasize

1. Automation

   "Notice how everything is automated. Developers just write code and XML comments, and the system handles the rest."

2. Consistency

   "The same system works across all repositories, providing a consistent experience."

3. Accessibility

   "Documentation is available in multiple ways - web browser, search API, and directly in your IDE."

4. Always Current

   "Because docs are generated from code, they're always up-to-date. No manual maintenance required."

5. Searchability

   "With Elasticsearch, we can search across all repositories instantly, finding exactly what we need."

---

Troubleshooting During Demo

If Azure Static Web App is slow

• Explain it's hosted on free tier
• Show local DocFX serve as alternative
• Emphasize production would be faster

If Elasticsearch query fails

• Check connection
• Use backup screenshots
• Explain the expected results

If MCP doesn't respond

• Restart VS Code
• Use manual Elasticsearch query
• Show screenshots of working queries

If pipeline is running

• Show previous successful run
• Explain what's currently happening
• Use pipeline YAML to explain stages

---

Demo Timing Summary

Demo	Duration	Critical?
Azure Static Web App	5 min	Yes
Elasticsearch Index	3 min	Yes
MCP Integration	2 min	Yes
Pipeline Execution	2 min	Optional
Total	10-12 min

---

Questions to Anticipate

During Demos

Q: "How often does the documentation update?"
A: "Every time we merge to main. The pipeline runs automatically and updates everything within 5-10 minutes."

Q: "Can we customize the look and feel?"
A: "Yes, DocFX supports custom templates and themes. We're using the default modern template now."

Q: "What if the build fails?"
A: "The pipeline will fail and notify us. We can see the error in the logs and fix it before merging."

Q: "How do we search across multiple repositories?"
A: "All repositories are indexed in the same Elasticsearch index, so searches automatically span all repos."

Q: "Can we version the documentation?"
A: "Not currently, but DocFX supports versioning if we need it in the future."

---

Success Criteria

The demo is successful if the audience:

• ✅ Understands the automated workflow
• ✅ Sees the quality of generated documentation
• ✅ Appreciates the search capabilities
• ✅ Recognizes the IDE integration value
• ✅ Feels confident they can use the system

---

End of Demo Script

Remember:

• Speak clearly and at a moderate pace
• Pause for questions
• Have fun showing off the system!
• Emphasize the benefits, not just the features