home / skills / lerianstudio / ring / writing-functional-docs

writing-functional-docs skill

safe

This skill helps you craft clear functional documentation with value-led structure, practical examples, and actionable steps for readers.

npx playbooks add skill lerianstudio/ring --skill writing-functional-docs

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

3.3 KB

---
name: ring:writing-functional-docs
description: |
  Patterns and structure for writing functional documentation including guides,
  conceptual explanations, tutorials, and best practices documentation.

trigger: |
  - Writing a new guide or tutorial
  - Creating conceptual documentation
  - Documenting best practices
  - Writing "how to" content

skip_when: |
  - Writing API reference → use writing-api-docs
  - Reviewing documentation → use documentation-review
  - Writing code → use dev-team agents

sequence:
  before: [documentation-review]

related:
  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](link)"
- **API reference links:** Connect to API docs: "Manage via [API](link) or [Console](link)"
- **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

Overview

This skill provides patterns and a clear structure for writing functional documentation: conceptual guides, getting-started tutorials, how-to tasks, and best-practice pages. It focuses on practical writing rules that make documentation scannable, actionable, and directly useful to readers. Use it to produce consistent, user-centered guides that prioritize value and clarity.

How this skill works

The skill inspects your intended document type and applies tailored templates and writing patterns: lead with value, use second person, present tense, and action-oriented headings. It enforces short paragraphs, suggests appropriate visual elements (tips, warnings, code examples, tables), and adds section dividers and linking patterns to improve navigation. It also provides a quality checklist to verify completeness before publishing.

When to use it

Creating a conceptual overview that explains core ideas and relationships
Authoring a getting-started guide for first-time users
Writing a how-to that walks users through a specific task step-by-step
Drafting best-practice documentation to show preferred patterns and common mistakes
Reviewing existing docs to improve clarity, tone, and structure

Best practices

Start every document with a one-sentence value statement: what the reader will learn or accomplish
Write in second person and present tense to keep instructions clear and immediate
Use action-oriented headings that describe what users will do, not what is in the section
Keep paragraphs to 2–3 sentences; use bullets for lists and numbered steps for procedures
Include working code examples, tip/warning boxes, and links to related docs or API references
End with clear next steps or links to deeper resources and run the quality checklist before publishing

Example use cases

A quick "Create your first account" tutorial with prerequisites, steps, and verification
A conceptual page explaining the architecture and how components interact
A how-to for a specific workflow, including preconditions, step-by-step commands, and troubleshooting
A best-practices article comparing common pitfalls and the recommended approaches
A documentation review where you reformat and refocus content to lead with reader value

FAQ

What is the difference between functional docs and API reference?

Functional docs explain why and how to use features; API reference lists endpoints, parameters, and exact behavior.

How should I format procedural steps?

Use numbered steps with clear verification steps and a brief troubleshooting section for common failures.