How to Improve Man Pages with Practical Examples: A Guide for Network Tools

Introduction

Man pages are the go-to reference for command-line tools, but they often lack the real-world examples that help beginners and infrequent users get started quickly. This guide walks you through the process of enhancing man pages for network diagnostic tools like tcpdump and dig by adding clear, beginner-friendly examples. Based on the successful experiences of contributors who added examples to these tools' official documentation, you'll learn how to identify needed examples, collaborate with maintainers, format content correctly (even in roff), and get your changes accepted. By the end, you'll have a repeatable method to improve any man page.

What You Need

• Basic knowledge of the command-line tool you want to document (e.g., tcpdump, dig)
• Access to a Unix-like system with the tool installed (or its source code)
• Text editor (any will do, but one with syntax highlighting for roff or Markdown is helpful)
• Familiarity with man page formatting (or willingness to learn roff basics, or use a converter)
• Patience for a review process – maintainers will check accuracy and style
• Optional: A Markdown-to-roff converter script (like the one mentioned in the original work) or pandoc

Step-by-Step Guide

Step 1: Identify Target Tools and Common Use Cases

Start by choosing tools that are widely used but have man pages lacking practical examples. tcpdump and dig are great candidates because they are powerful yet have many flags and options that confuse new users. For each tool, ask yourself: “What do most people actually want to do with this tool?” For tcpdump, common tasks include:

• Capture packets on a specific interface
• Filter by host or port
• Save packets to a file (-w) with live summary (-v)
• Read a saved file

For dig, typical uses are:

• Query a specific DNS record type (e.g., MX, NS)
• Query a specific nameserver
• Perform a reverse DNS lookup
• Short form output (+short)

Compile a short list of the most essential one-liner examples – aim for 5–10 that cover 80% of user needs.

Step 2: Consult Maintainers and Experienced Users

Before writing, reach out to the tool's maintainers (via mailing lists, GitHub issues, or IRC) to verify your assumptions. Ask questions like: “What are the most common flags you see users struggling with?” or “Are there any hidden features that beginners often miss?” In the original work, the author learned from tcpdump maintainers that -v when used with -w prints a live count of captured packets – a valuable tip that wasn't obvious. Engaging the community ensures your examples are accurate and highlights features you might overlook. It also builds goodwill and makes the review process smoother later.

Step 3: Draft Clear, Beginner-Friendly Examples

Write each example following this structure:

• Goal (one-line description of what the example does)
• Command (exact command to type)
• Explanation (brief, plain-English breakdown of flags and expected output)
• Sample output (or a note about what to look for)

For instance:

Goal: Capture 10 packets from the eth0 interface and save to a file.
Command: tcpdump -i eth0 -c 10 -w capture.pcap -v
Explanation: -i eth0 selects the interface, -c 10 limits to 10 packets, -w writes to file, -v prints a count of packets captured so far (useful for feedback).

Keep language simple – avoid jargon unless you define it. Assume the reader has never used the tool before but knows basic terminal usage.

Step 4: Format the Examples for the Man Page

Man pages use the roff language (e.g., .TP, .IP, .PP, etc.). Writing directly in roff can be tedious. A practical solution is to write your examples in Markdown and then convert them to roff. The original contributor created a custom Markdown-to-roff script that mapped common Markdown syntax (headings, lists, code blocks) to corresponding roff macros that matched the existing man page style. You can do the same: start by examining the current man page (man tcpdump | col -b or view the source) to see which macros are used. Then write your examples in a structured plain text format (like Markdown) and run a conversion tool. Alternatively, use pandoc with a proper template, but be prepared to tweak the output. The key is to produce a patch that integrates seamlessly with the existing document.

Step 5: Submit a Patch for Review and Iterate

Once your examples are formatted, generate a diff against the current man page source (using diff -u or a Git patch). Submit it to the project's issue tracker or mailing list with a clear description of what you added and why. Maintainers will likely request changes – accept feedback graciously. The original author thanked Denis Ovsienko, Guy Harris, and Ondřej Surý for their reviews. Be prepared to adjust wording, fix inaccuracies, or tweak formatting. This collaborative process ensures the final result is both correct and helpful. After acceptance, your examples become part of the official documentation, benefiting countless users.

Tips for Success

• Start small – even 3–5 high-quality examples are better than none. You can always expand later.
• Test every command – run each example in your own environment to confirm it works and produces sensible output.
• Avoid overly complex examples – focus on the most frequent tasks. Save advanced use cases for later sections.
• Use the EXAMPLES section – most man pages already have a designated place for examples. Put your content there.
• Check for existing examples – if the tool already has some examples, build on them instead of starting from scratch.
• Consider cross-referencing – inside the man page, you can add internal anchor links (e.g., see the Examples section) if the format supports it.
• Share your script – if you write a converter, share it with the community. It may help others contribute to man pages.
• Remember the goal: Your additions should make the man page as readable and useful as a top blog post, but with guaranteed accuracy from maintainer review.

By following these steps, you can transform a dry man page into a friendly, practical guide that empowers users to master tools like tcpdump and dig quickly. Good documentation is a gift that keeps giving – and it all starts with a few well-chosen examples.