How to Make Man Pages More Accessible: A Guide to Adding Effective Examples for tcpdump and dig

Introduction

Have you ever opened a man page only to feel overwhelmed by dense syntax and cryptic options? You're not alone. Many users, especially those who only occasionally reach for tools like tcpdump or dig, prefer quick examples over reading paragraphs of documentation. That's why adding a well-crafted examples section can transform a man page from a wall of text into a practical, friendly reference.

This guide walks you through the process of improving man pages by writing and integrating beginner-friendly examples—just like the recent updates to the tcpdump and dig man pages. You'll learn how to focus on the most common use cases, collaborate with maintainers, and even handle the quirks of formatting tools like roff—all while keeping the information accurate and easy to digest.

What You Need

• Access to the tool's source repository – Usually hosted on GitHub, GitLab, or similar platforms.
• Basic command-line experience – Familiarity with the tool (tcpdump or dig) is helpful but not mandatory.
• Text editor or Markdown editor – For drafting example commands and explanations.
• Understanding of the man page format – Whether it's roff, mdoc, or plain text, know the syntax used by the project.
• Patience and willingness to review – Expect feedback from maintainers; it's part of the process to ensure accuracy.

Step-by-Step Guide

Step 1: Identify Your Audience and Goal

Before writing a single example, define who the examples are for. In the case of tcpdump and dig, the goal was to serve beginners and infrequent users – people who don’t use the tool daily and need a quick reminder of how it works.

• Ask yourself: What is the simplest, most common task someone would want to accomplish? For tcpdump, that might be capturing packets on an interface. For dig, it's looking up an IP address for a domain.
• Resist the urge to cover every edge case. Stick to the absolute basics that give immediate value.

Step 2: Draft Clear, Minimal Examples

With your audience in mind, write down 3–5 examples that demonstrate the core functionality. Use a flat, instructional tone. For each example, include:

• The exact command line
• A short, plain-English explanation of what it does
• Any important output details or flags worth noting

Example for tcpdump:

tcpdump -i eth0

Captures all packets on the eth0 interface. Press Ctrl+C to stop.

Example for dig:

dig example.com

Returns DNS records for example.com, including the A (IPv4) address.

Keep it short. You can later expand if maintainers suggest additions.

Step 3: Submit Your Draft to the Project Maintainers

Open an issue or pull request on the project's repository. Present your examples as a starting point. Be open about your intent: “I’d like to add beginner examples to the man page.” This is what worked for the tcpdump and dig updates—maintainers like Denis Ovsienko, Guy Harris, and Ondřej Surý provided valuable feedback.

• Use the repository's preferred discussion channel.
• Be prepared to defend or modify your examples based on real-world accuracy.

Step 4: Incorporate Feedback from Maintainers

This step is crucial. Maintainers often know hidden gems—like adding the -v flag to tcpdump -w out.pcap to get live packet counts. Such tips can make your examples far more useful than a simple blog post.

• Listen carefully to suggestions about phrasing, flag usage, and edge cases.
• Test every command yourself to ensure it works as described.
• If a maintainer says a flag is rarely used, consider removing it to keep examples lean.

In the tcpdump example, I learned that -v isn't just verbose—it prints a live summary when writing to a file. That’s exactly the kind of insight you want to pass on.

Step 5: Format the Examples in the Man Page Language

Most man pages are written in roff, a markup language that can be intimidating. But you don’t have to master roff to contribute. One approach is to write your examples in Markdown and then convert them.

For the tcpdump project, a simple Markdown-to-roff conversion script was written to handle the formatting. This allowed the contributor to focus on content, not syntax. Alternatives:

• Use pandoc (though output may need tweaking).
• Hand-write the roff code if you’re comfortable.
• Ask maintainers if they accept patches in a different format.

Whichever method you choose, ensure the final man page renders correctly on your system before submitting.

Step 6: Test and Review the Final Output

Run man ./yourfile. to preview the page. Check for:

• Proper indentation and line breaks
• Example commands clearly separated from explanations
• No broken formatting (e.g., missing bold for commands)

If something looks off, adjust the roff markup or your conversion script. This is where the small details matter—a poorly formatted man page can frustrate readers.

Step 7: Encourage Continued Improvement

Once your examples are merged, consider the job done—or just the start. Man pages can evolve. Encourage others to contribute more examples, or add new ones yourself when the tool updates. Good documentation grows with the community.

Tips for Success

• Focus on accuracy above all. A man page can be 100% correct—unlike many online tutorials. Use maintainer reviews to catch mistakes.
• Don't try to learn roff from scratch. Use a conversion script or ask for help. The goal is better documentation, not becoming a roff expert.
• Start with one tool. Pick tcpdump or dig—or any utility you use and love. You'll learn the process and gain confidence.
• Leverage community knowledge. When you present your examples, you invite maintainers to share hidden features (like the -v flag trick). That enriches everyone.
• Be patient with reviews. Documentation changes often get less attention than code, but maintainers appreciate thoughtful contributions. It may take a few rounds.
• Consider writing in Markdown first. It’s easier to get feedback on content before wrestling with roff. Convert later.
• Keep it simple. A handful of rock-solid examples is better than twenty half-explained ones. Beginners will thank you.

Improving man pages is a rewarding way to give back to open-source projects. You don’t need to be a senior developer—just someone who cares about making tools more accessible. Start with one example, one pull request, and watch the documentation get better for everyone.