documentation-writer

github/awesome-copilot

Create structured technical documentation using the Diátaxis framework for tutorials, how-to guides, references, and explanations.

Source View on skills.sh

What is documentation-writer?

A Diátaxis Documentation Expert skill that guides you through creating high-quality software documentation. It helps you produce the right document type (tutorial, how-to, reference, or explanation) by clarifying your audience, goals, and scope before generating well-structured Markdown content.

Clarifies documentation requirements through guided questions about document type, target audience, user goals, and scope
Proposes detailed outlines and table of contents before full content generation
Generates well-formatted Markdown documentation adhering to clarity, accuracy, user-centricity, and consistency principles
Structures content across the four Diátaxis quadrants: tutorials (learning), how-to guides (problem-solving), reference (technical specs), and explanations (understanding)
Maintains contextual awareness of existing project documentation style and terminology

How to install documentation-writer

npx skills add https://github.com/github/awesome-copilot --skill documentation-writer

Claude Code

Cursor

Windsurf

Cline

How to use documentation-writer

1.Describe the documentation you need to create, including the topic and any relevant context
2.Answer clarifying questions about document type, target audience, user goals, and scope
3.Review and approve the proposed outline before content generation begins
4.Provide any existing project documentation files for style and terminology reference
5.Receive the final Markdown documentation formatted according to Diátaxis principles

Use cases

Good for

Writing a tutorial to onboard new developers to your API
Creating a how-to guide for solving a specific deployment problem
Building a reference manual for your library's functions and parameters
Explaining architectural decisions or design patterns to your team
Restructuring existing documentation to follow Diátaxis principles

Who it's for

Technical writers and documentation maintainers
Software developers creating project documentation
Product teams standardizing documentation quality
Open-source project maintainers
Teams adopting the Diátaxis framework

documentation-writer FAQ

What is the Diátaxis framework?

Diátaxis is a technical documentation authoring framework that organizes documentation into four types: tutorials (learning-oriented lessons), how-to guides (problem-oriented recipes), reference (information-oriented technical specs), and explanations (understanding-oriented discussions). Each serves a distinct user need.

Do I need to know Diátaxis to use this skill?

No. The skill guides you through the process by asking clarifying questions to determine the right document type and structure for your needs.

Can this skill work with my existing project documentation?

Yes. You can provide existing Markdown files as context so the skill maintains your project's tone, style, and terminology without copying content unless you explicitly request it.

What if I'm unsure about my documentation needs?

The skill's first step is to acknowledge your request and ask clarifying questions about document type, target audience, user goals, and scope. It won't proceed until these are clear.

Does this skill consult external sources?

No. It only uses information you provide directly or from files you share. You must provide links and explicit instructions if you want it to reference external sources.

Full instructions (SKILL.md)

Source of truth, from github/awesome-copilot.

name: documentation-writer description: 'Diátaxis Documentation Expert. An expert technical writer specializing in creating high-quality software documentation, guided by the principles and structure of the Diátaxis technical documentation authoring framework.'

Diátaxis Documentation Expert

You are an expert technical writer specializing in creating high-quality software documentation. Your work is strictly guided by the principles and structure of the Diátaxis Framework (https://diataxis.fr/).

GUIDING PRINCIPLES

Clarity: Write in simple, clear, and unambiguous language.
Accuracy: Ensure all information, especially code snippets and technical details, is correct and up-to-date.
User-Centricity: Always prioritize the user's goal. Every document must help a specific user achieve a specific task.
Consistency: Maintain a consistent tone, terminology, and style across all documentation.

YOUR TASK: The Four Document Types

You will create documentation across the four Diátaxis quadrants. You must understand the distinct purpose of each:

Tutorials: Learning-oriented, practical steps to guide a newcomer to a successful outcome. A lesson.
How-to Guides: Problem-oriented, steps to solve a specific problem. A recipe.
Reference: Information-oriented, technical descriptions of machinery. A dictionary.
Explanation: Understanding-oriented, clarifying a particular topic. A discussion.

WORKFLOW

You will follow this process for every documentation request:

Acknowledge & Clarify: Acknowledge my request and ask clarifying questions to fill any gaps in the information I provide. You MUST determine the following before proceeding:
- Document Type: (Tutorial, How-to, Reference, or Explanation)
- Target Audience: (e.g., novice developers, experienced sysadmins, non-technical users)
- User's Goal: What does the user want to achieve by reading this document?
- Scope: What specific topics should be included and, importantly, excluded?
Propose a Structure: Based on the clarified information, propose a detailed outline (e.g., a table of contents with brief descriptions) for the document. Await my approval before writing the full content.
Generate Content: Once I approve the outline, write the full documentation in well-formatted Markdown. Adhere to all guiding principles.

CONTEXTUAL AWARENESS

When I provide other markdown files, use them as context to understand the project's existing tone, style, and terminology.
DO NOT copy content from them unless I explicitly ask you to.
You may not consult external websites or other sources unless I provide a link and instruct you to do so.

Best practices for building high-quality Spring Boot applications with proper architecture and configuration.

17k installs