The Four Types of Software Docs (And How to Get Them Right)

Great software deserves great documentation. Whether you're building an open-source library, a cutting-edge app, or an enterprise tool, documentation is what turns curious visitors into confident users—and confident users into dedicated contributors.

But not all documentation is created equal. Mixing different types into a single, chaotic resource makes it harder for users to find what they need and harder for you to maintain. The key? Structure.

Let’s break down the four essential types of documentation and how to do each one right.

1. Tutorials: The First Steps

Think of a tutorial as a hands-on onboarding experience. It’s a step-by-step guide designed to help new users achieve something concrete, giving them their first quick win with your software.

🔹 Goal: Help a beginner accomplish a small but meaningful task.
🔹 Tone: Friendly, straightforward, and hand-holding.
🔹 Avoid: Deep technical explanations or background information.

✅ Example: A tutorial for Next.js might guide users through building a simple blog—setting up a Next.js project, fetching posts from an API, and displaying them on a page. By the end, they’ll have a working site and a sense of accomplishment.

2. How-To Guides: Solving Real-World Problems

Once users have a basic grasp of your software, they’ll start looking for specific solutions. How-to guides are like recipes—short, direct instructions to help users achieve a goal.

🔹 Goal: Solve a well-defined, real-world problem.
🔹 Tone: Concise and action-oriented.
🔹 Avoid: Long-winded explanations or unnecessary background info.

✅ Example: A how-to guide for Supabase might explain how to implement row-level security in a PostgreSQL database. It assumes the user is familiar with Supabase and focuses only on setting up policies, writing SQL rules, and testing the security model.

3. Reference Guides: The Encyclopedia of Your Project

Reference documentation is where users go when they need precise, technical details—not explanations, not tutorials, just facts. It should be structured like your codebase, making it easy for users to navigate.

🔹 Goal: Provide clear, comprehensive information about your software’s components.
🔹 Tone: Objective, precise, and to-the-point.
🔹 Avoid: Narrative explanations or problem-solving.

✅ Example: A reference guide for OpenAI’s API would include detailed documentation on API endpoints, listing parameters, request formats, and response structures with sample JSON payloads.

4. Discussions: The Bigger Picture

Discussions (or background material) provide insight into design decisions, trade-offs, and best practices. They help users understand not just how your software works, but why it works that way.

🔹 Goal: Explain the reasoning behind design choices.
🔹 Tone: Thoughtful, analytical, and open-ended.
🔹 Avoid: Step-by-step instructions—this is about "why," not "how."

✅ Example: A discussion on React Server Components might explore why they were introduced, their advantages over traditional client-side rendering, and how they compare to existing solutions like Server-Side Rendering (SSR).

Keep It Separate, Keep It Simple

The biggest mistake? Blurring these categories. Tutorials shouldn’t feel like reference manuals. How-to guides shouldn’t turn into lengthy discussions. Keep each type of documentation focused on its purpose, and your users will thank you.

Why It Matters

📌 Better user adoption – Clear documentation reduces frustration and helps users succeed faster.
📌 Lower maintenance burden – Well-structured docs are easier to update and expand.
📌 More contributions – When people can quickly understand your project, they’re more likely to contribute.

So if your documentation is a bit of a mess right now, don’t worry—start by organizing it into these four categories. Your project (and your users) will be better for it.

Big thanks to Daniele Procida for his insightful great speech at PyCon Australia 2017, which inspired this post! 🚀