Crafting Effective Man Page Examples: A Practical Guide for Open Source Documentation

Introduction

Man pages are the backbone of Unix-like system documentation, yet they often suffer from being dry, hard to parse, and lacking practical examples. The experience of improving the tcpdump and dig man pages by adding well-crafted example sections proved that even a small effort can dramatically enhance usability for beginners and infrequent users. This guide distills that process into a step-by-step method you can apply to any command-line tool’s man page.

What You Need

• Source man page file (typically in roff or mdoc format) for the tool you want to improve.
• A text editor (vim, emacs, VS Code, or any plain-text editor).
• Familiarity with the tool – you should understand its core use cases and flags.
• Access to the tool’s maintainers for review (via mailing list, issue tracker, or chat).
• Optional but helpful: A Markdown-to-roff converter (like the lightweight script the tcpdump project used) to simplify formatting.

Step-by-Step Guide

Step 1: Define Your Audience and Scope

Begin by deciding exactly who you’re writing for. The tcpdump and dig examples targeted infrequent users—people who reach for the tool once every few months and need a quick reminder. Avoid advanced or edge-case scenarios. Keep examples minimal and self-contained. For instance, a basic dig example might just show querying a single domain with default output, while a tcpdump example could show filtering by host and protocol.

Step 2: Collect Accurate, Authoritative Information

Even seemingly simple questions (e.g., “What are the most commonly used tcpdump flags?”) can uncover insights you wouldn’t find alone. Reach out to the tool’s maintainers. The author of the original man page improvements learned from Denis Ovsienko and Guy Harris that tcpdump -w out.pcap combined with -v prints a live packet count summary—a small but valuable detail. Documenting this kind of real-world knowledge makes the man page trustworthy and practical.

Step 3: Choose Basic but Useful Examples

List the top 3–5 use cases that cover 80% of everyday usage. For example:

• Performing a simple DNS lookup (dig example.com)
• Capturing traffic on a specific interface (tcpdump -i eth0)
• Saving captured packets to a file (tcpdump -w capture.pcap)
• Filtering by port number (tcpdump port 80)
• Showing only packets from a source IP (tcpdump src 192.168.1.1)

For each example, include the exact command, a brief explanation of what it does, and the expected output (or a screenshot-like text block).

Step 4: Write Clear, Concise Example Descriptions

Use active voice and plain English. Start each example with a bold heading (e.g., Basic DNS Query). Then provide the command in a code block, followed by a short paragraph explaining flags and output. Avoid jargon unless it’s defined earlier in the man page. The goal is to let someone who has never used the tool follow along and get meaningful results.

Step 5: Seek Review from Maintainers and Peers

Accuracy is paramount. Send your draft to the project’s mailing list or maintainers directly. Expect feedback on both the correctness of examples and the clarity of the writing. In the tcpdump case, reviewers like Ondřej Surý provided insights that improved the examples. Be open to revisions—this step ensures your documentation is close to 100% accurate.

Step 6: Format in the Man Page Language

Most man pages use the roff (or mdoc) language, which can be intimidating. You have two options:

• Learn roff basics – enough to add simple lists, paragraph breaks, and code blocks.
• Use a Markdown-to-roff converter – the tcpdump project created a lightweight script to convert Markdown into roff, preserving the man page’s existing style. You can write examples in Markdown, then run the script. While pandoc exists, a custom script may produce output that better matches the original formatting.

Always verify the final output with man -l yourfile.1 to check for rendering errors.

Step 7: Test and Iterate

After formatting, read through the man page as a real user. Try each example exactly as written. If a command doesn’t produce the described output, fix it. Over time, feedback from the community will highlight missing examples or unclear explanations. Keep the examples section living documentation—update it when new flags become common.

Tips for Success

• Start with the most common mistakes – examples that show what not to do (e.g., forgetting sudo for packet capture) can be very instructive.
• Use consistent terminology – if you refer to “interface” and “link” interchangeably, your readers will get confused.
• Keep examples short – ideally no more than three commands per example block. Brevity is key for quick scanning.
• Provide real output – when possible, include the actual text that appears on the terminal, not a stylized version.
• Collaborate early – talking to maintainers before writing can steer you away from dead ends and toward the most needed improvements.

Remember, a man page with great examples can be as helpful as a top-notch blog post—except it’s guaranteed to be correct because it’s been reviewed by the people who know the tool best. That’s the power of community-tested documentation.