writing-functional-docs

Patterns and structure for writing functional documentation including guides,conceptual explanations, tutorials, and best practices documentation.

⭐25stars🔀1forks📁View on GitHub🕐Updated Dec 31, 2025⬇️2downloads

When & Why to Use This Skill

This Claude skill provides a comprehensive framework and standardized patterns for creating high-quality functional documentation. It streamlines the process of writing conceptual explanations, step-by-step tutorials, and best practice guides by enforcing professional technical writing standards, such as action-oriented headings, second-person perspective, and concise paragraph structures to improve user comprehension and engagement.

Use Cases

  • Case 1: Developing 'Getting Started' guides to ensure a seamless onboarding experience for new product users.
  • Case 2: Creating in-depth conceptual documentation to explain complex system architectures and core product logic.
  • Case 3: Authoring task-focused 'How-To' tutorials that guide users through specific workflows and troubleshooting steps.
  • Case 4: Establishing best practice manuals that highlight optimal usage patterns and common pitfalls to avoid.
  • Case 5: Standardizing existing documentation to follow a consistent voice, tone, and structural layout for better readability.
namering:writing-functional-docs
description|
trigger|
skip_when|
before[documentation-review]
similar[writing-api-docs]
complementary[voice-and-tone, documentation-structure]

Writing Functional Documentation

Functional documentation explains concepts, guides users through workflows, and helps them understand "why" and "how" things work. This differs from API reference, which documents "what" each endpoint does.

Document Types

Type Purpose Key Sections
Conceptual Explains core concepts and how things work Definition → Key characteristics → How it works → Related concepts
Getting Started First task with the product Intro → Prerequisites → Numbered steps → Next steps
How-To Task-focused for specific goals Context → Before you begin → Steps → Verification → Troubleshooting
Best Practices Optimal usage patterns Intro → Practice sections (Mistake/Best practice) → Summary

Writing Patterns

Lead with Value

Start every document with what the reader will learn or accomplish.

✅ This guide shows you how to create your first transaction in under 5 minutes.

❌ In this document, we will discuss the various aspects of transaction creation.

Use Second Person

Address the reader directly.

✅ You can create as many accounts as your structure demands.

❌ Users can create as many accounts as their structure demands.

Present Tense

Use for current behavior.

✅ Midaz uses a microservices architecture.

❌ Midaz will use a microservices architecture.

Action-Oriented Headings

Indicate what the section covers or what users will do.

✅ Creating your first account

❌ Account creation process overview

Short Paragraphs

2-3 sentences maximum. Use bullets for lists.


Visual Elements

Element Usage
Info box > **Tip:** Helpful additional context
Warning box > **Warning:** Important caution
Code examples Always include working examples for technical concepts
Tables For comparing options or structured data

Section Dividers

Use --- to separate major sections. Improves scannability.


Linking Patterns

  • Internal links: Link concepts when first mentioned: "Each Account is linked to a single Asset"
  • API reference links: Connect to API docs: "Manage via API or Console"
  • Next steps: End guides with clear next steps

Quality Checklist

  • Leads with clear value statement
  • Uses second person ("you")
  • Uses present tense
  • Headings are action-oriented (sentence case)
  • Paragraphs are short (2-3 sentences)
  • Includes working code examples
  • Links to related documentation
  • Ends with next steps
  • Follows voice and tone guidelines