documentation

Overview of documentation skill

What the documentation skill does

The documentation skill helps you create, reorganize, and review technical content using the Diátaxis model: tutorials, how-to guides, reference, and explanation. It is most useful when you need more than a generic writing prompt and want a documentation structure that matches the user’s intent.

Who should use it

Use this documentation skill if you are doing technical writing for product docs, API docs, onboarding flows, or internal developer documentation. It is a strong fit when you already know the topic but need help deciding the right doc type, shaping the outline, or fixing docs that confuse readers.

Why it stands out

Its main value is classification and structure, not just prose generation. The documentation install is designed to help you separate learning content from task content, keep reference material factual, and reduce the common mistake of mixing explanation, procedure, and API details in one page.

How to Use documentation skill

Install and open the right files

Run npx skills add mcollina/skills --skill documentation to install the documentation skill. Start with SKILL.md, then inspect tile.json for the short summary and metadata. Because this repo has no supporting rules/, references/, or scripts/ folders, the core behavior comes from the main skill file itself.

Turn a vague request into a useful prompt

The skill works best when you provide the doc goal, audience, and source material. For example, instead of “write docs for my API,” ask: “Create a how-to guide for new backend engineers who need to authenticate with our API using an API key; include prerequisites, setup steps, one success example, and common failure cases.” That kind of input helps the documentation usage stay focused and makes the output easier to publish.

Use the Diátaxis decision first

Before asking for content, decide whether the user needs a tutorial, how-to guide, reference page, or explanation. A tutorial teaches by doing; a how-to guide solves one task; reference documents facts; explanation explains concepts and tradeoffs. If you skip this step, the output may read well but still fail the documentation guide standard.

Suggested workflow for better output

Read the source product notes, decide the target doc type, then ask the skill to produce an outline before the full draft if the scope is large. For documentation for Technical Writing, this usually gives better results than asking for a full page immediately, because you can correct scope, terminology, and missing prerequisites early.

documentation skill FAQ

Is this better than a normal prompt?

Yes, when structure matters. A normal prompt can draft text, but the documentation skill is built to help you choose the right documentation pattern first, which is often the real problem in technical writing.

When should I not use it?

Do not use it for marketing copy, release notes, or opinion essays. It is also not the best fit when you need a single quick answer without source context, because documentation work usually depends on audience, constraints, and the task being documented.

Is it beginner-friendly?

Yes, if you can describe the goal in plain language. Beginners get the most value from the documentation skill when they share the product, the reader level, and the exact action or concept they want documented.

Does it fit developer docs and API docs?

Yes. The documentation skill is well suited to API documentation, setup guides, and internal developer docs, especially when you need to keep reference material separate from tutorials or how-to guides.

How to Improve documentation skill

Give the skill the right raw material

The best results come from concrete inputs: the product name, target reader, doc type, current state, and the exact outcome the reader should achieve. For example, “Update our authentication docs for first-time integrators; they need to generate a token and test one request” is much stronger than “improve our docs.”

State constraints early

Mention platform, version, voice, terminology, and any policy limits up front. If your documentation install has to fit an existing style guide, a specific SDK, or a docs site format, say so before generation; otherwise the output may be structurally correct but still unusable.

Watch for the most common failure modes

The biggest problems are choosing the wrong Diátaxis type, mixing explanation into a procedure, and writing reference content with tutorial language. If the first draft feels too broad, ask for a split into separate pages, tighter prerequisites, or a rewrite that removes conceptual filler from task steps.

Iterate with targeted edits

After the first pass, improve the documentation skill output by asking for one change at a time: “make this a pure how-to guide,” “add missing prerequisites,” “convert examples into API reference style,” or “rewrite for advanced users.” That kind of iteration usually produces a better documentation guide than asking for a general polish pass.