How to Add Effective Examples to Man Pages

Adding clear, practical examples to man pages can turn a dense reference into a useful learning tool. This guide walks you through the process of improving man pages for command-line tools like tcpdump and dig, based on real experience that doubled as a documentation improvement project. You'll learn how to identify the most basic use cases, write simple examples, handle conversion to roff, and work with maintainers to ensure accuracy. Whether you're a power user or a documentation enthusiast, these steps will help you make man pages more accessible for everyone.

What You Need

• Basic familiarity with the command-line tool you want to document
• Access to the tool's source repository (e.g., GitHub, GitLab)
• Text editor
• Optional: A markdown-to-roff conversion script (or pandoc) if the man page uses the roff language
• Patience for review cycles and maintainer feedback

Step-by-Step Instructions

Step 1: Define Your Audience and Goal

Before writing anything, clarify who will benefit: beginners and infrequent users. The goal is to show the absolute most basic ways to use the tool—commands that answer "how do I do X?" without assuming prior knowledge. For example, tcpdump -i eth0 to capture traffic on an interface, or dig example.com to look up DNS records. Keep your target audience in mind throughout the process; it makes it easy to explain your changes to maintainers later.

Step 2: Gather the Most Common Use Cases

Research the tool's most frequently used options and commands. Look at:

• Existing man pages (note what's missing)
• Blog posts and Stack Overflow answers
• Community forums and mailing lists
• Your own experience: what do you always have to look up?

For tcpdump, common cases include: saving packets to a file with -w, reading from a file with -r, filtering with expressions. For dig, example use cases are querying specific record types (A, MX, NS) and querying a specific DNS server. Write down 5–10 of the simplest, most universal examples.

Step 3: Write Clear, Minimal Examples

For each use case, craft an example that is:

• Short: Typically one line of code with a brief explanation.
• Accurate: Test it yourself to ensure it works exactly as shown.
• Useful: Avoid edge cases; stick to the 80% use scenario.

Include a short description before each example. Example format:

Capture packets on the eth0 interface:
  $ tcpdump -i eth0

Save captured packets to a file, with a live count:
  $ tcpdump -w output.pcap -v

Notice the -v flag for live packet count—a tip you may not have known that even experienced users appreciate.

Step 4: Choose a Conversion Method (If Needed)

Many traditional man pages are written in the roff language, which can be intimidating. To avoid learning roff, you can:

• Write your examples in Markdown and use a custom script to convert Markdown to roff. The original author of this guide wrote a minimal markdown-to-roff script that reused existing macros from the man page.
• Alternatively, use pandoc with roff output, but be prepared to adjust the output style to match the man page's conventions.

If the man page is already in a modern format (e.g., mdoc or pod), follow its conventions directly.

Step 5: Insert Examples into the Man Page

Locate the appropriate section of the man page—usually after the options list or in a new EXAMPLES section. If none exists, add one. Place your examples in logical order, from simplest to slightly more advanced. Ensure your conversion preserves formatting (bold for commands, italics for variables). Review the existing man page structure to maintain consistency.

Step 6: Submit for Review and Iterate

Push your changes to a branch or submit a patch. Be prepared for feedback from maintainers—they will catch inaccuracies, suggest better flags, or recommend additional examples. For instance, the tcpdump maintainer Denis Ovsienko and Guy Harris provided valuable input that improved the output. Engage positively: review comments are an opportunity to learn, not a critique of your writing. Incorporate suggestions and resubmit until the examples are both correct and clear.

Step 7: Validate Accuracy and Test

Before finalizing, run each example through the actual tool. Confirm that:

• The command behaves exactly as described
• The output shown (if any) matches reality
• Flags and options are spelled correctly

Documentation that is even slightly wrong loses trust. Take the time to double-check.

Step 8: Celebrate and Maintain

Once your examples are merged, thank the maintainers and the community. Your contribution makes the tool more approachable. Periodically check if new versions of the tool have added options that warrant updating the examples—keep them current.

Tips for Success

• Stay basic: Resist the urge to include obscure flags. Your audience is beginners—stick to what 90% of users need.
• Use real output snippets: If showing command output, include a representative snippet to set expectations.
• Keep language simple: Avoid jargon; explain every flag in one sentence.
• Get feedback early: Ask a colleague or roomate to read your examples. If they can follow them without Googling, you're on the right track.
• Leverage maintainer knowledge: Maintainers often have hidden gem flags – like tcpdump -v with -w – that are perfect for your examples.
• Document your process: If you write a conversion script, share it with the community. It might help others contribute.

Improving man pages is a rewarding way to give back to open-source tools. With these steps, you can transform a dense reference into a friendly guide that helps users get started quickly.