Documentation

how-to/README.md

About How-to Guides

What's Here

Problem-oriented documentation with practical recipes for accomplishing specific tasks.

Current guides:

  • create-component.md - Complete component creation
  • modify-component.md - Add features to components
  • build-locally.md - Build and run locally
  • deploy.md - Deploy to production
  • run-tests.md - Testing components
  • troubleshoot-issues.md - Fix common problems
  • migrate-to-dotnet-10.md - Upgrade to .NET 10

What Belongs Here

How-to guides are recipes that:

  • Solve a specific problem
  • Provide step-by-step instructions
  • Assume some knowledge of Dynaplex
  • Focus on getting something done

Examples of good how-to guides:

  • "How to add authentication to a component"
  • "How to configure HTTPS certificates"
  • "How to scale a service in production"
  • "How to debug inter-service communication"
  • "How to migrate a database schema"

What Doesn't Belong Here

❌ Teaching fundamentals → Use tutorials/
❌ Technical reference → Use reference/
❌ Explaining concepts → Use explanation/
❌ Routine operations → Use operations/

How to Think About This

Analogy: A cookbook

  • How-to: "How to make sourdough bread" (recipe for a specific dish)
  • Not how-to: "Learn to bake" (that's a tutorial)
  • Not how-to: "What is yeast?" (that's explanation)
  • Not how-to: "Flour types reference" (that's reference)

Key characteristics:

  • Goal-oriented - Accomplishing a specific task
  • Assumes knowledge - Reader knows the basics
  • Flexible - Reader may adapt to their needs
  • Multiple paths - May offer alternative approaches
  • Practical - Real-world scenarios

Writing Guidelines

Structure

  1. Clear title - "How to [accomplish specific goal]"
  2. Prerequisites - Required knowledge/setup
  3. Steps - Sequential instructions
  4. Variations - Alternative approaches (if applicable)
  5. Troubleshooting - Common issues
  6. Related guides - What to do next

Style

  • Be direct and concise
  • Assume reader knows Dynaplex basics
  • Focus on the task, not teaching concepts
  • Provide context when needed
  • Show real examples from the codebase

Example Template

# How to [Do Specific Thing]

[One sentence: what this guide accomplishes]

## Prerequisites

- [Required knowledge]
- [Required setup]

## Steps

### 1. [First Action]

[Instructions with code examples]

### 2. [Second Action]

[Instructions]

## Alternative Approaches

### Using [Method A]

[When to use this approach]
[Steps]

### Using [Method B]

[When to use this approach]
[Steps]

## Troubleshooting

**Problem:** [Common issue]
**Solution:** [How to fix]

## Next Steps

- [Related how-to]
- [Related reference]

When to Create a How-to Guide

Create a how-to when:

  • ✅ You're solving a specific problem
  • ✅ The reader has basic Dynaplex knowledge
  • ✅ There are clear steps to follow
  • ✅ The task is commonly needed

Don't create a how-to when:

  • ❌ Teaching fundamentals (use tutorial)
  • ❌ Providing reference info (use reference)
  • ❌ Explaining concepts (use explanation)

Organizing How-tos

Group related how-tos by category:

  • Component Development - create, modify, test
  • Build & Deployment - build, publish, deploy
  • Operations - monitor, scale, troubleshoot
  • Migration - upgrade, migrate data

Use clear, action-oriented filenames:

  • ✅ deploy-to-azure.md
  • ✅ add-database-to-component.md
  • ❌ deployment.md (too vague)
  • ❌ azure.md (not action-oriented)

Diátaxis Quadrant

How-to guides are:

  • Practical (doing) not theoretical
  • Focused on a goal not on learning
  • Task-oriented not study-oriented
  • Assume knowledge not introductory

Questions? See Documentation Setup