Documentation: man pages vs tldr

In today's blog post, I'm gonna compare two approaches to writing documentation: reference vs. recipes. Now, the point is not to determine which one is better – they both have their place – but to showcase the two approaches using two command-line documentation tools as examples.

Personally, I'm a fan of the recipe style. When I started programming back in the day, I ended up starting with PHP and probably the main reason why I ever learned to code was the User Contributed Notes section in PHP's documentation. Reading reference documentation like API docs or the reference part of PHP's docs is really hard. The more experienced you become in development, the easier they become to read and once you learn to read them, they become often the fastest because it's easier to find exactly what you need.

One downfall of recipes is that they are incomplete. Recipes only cover specific use cases and don't go further into describing the options and alternatives. So unless your use case is listed as a recipe, you'd be out of luck. So having a full and complete reference documentation is also needed.

Let's take a look at the documentation page for PHP's rsort. First, you'll see the function description, then a list of parameters, what the function returns and a few examples. That's the reference part (well, the examples are more of a recipe part already). And it's great when you want to see what order the arguments are passed or what flags does it support for sorting.

The reference documentation starts from the implementation and usage point of view: how is this feature made and how to use it.

But then there's the User Contributed Notes section, the recipes, provided by the community. Recipes start from a different place: they answer the question "how to do X?" with practical examples. For example, at the time of writing, the top note provides the code for "A cleaner (I think) way to sort a list of files into reversed order based on their modification date." It adds a bit of extra code around the function call itself because we rarely use these functions in isolation but as part of other code.

When I was learning computer science at the university, I bought a lot of programming cookbooks like JD Long's & Paul Teetor's R Cookbook and Anthony Molinaro's SQL Cookbook. And I loved reading them more than I liked reading R documentation or SQL reference guides. Because they helped me learn how to solve real-life problems.

So let's take a look at two example cases from the command-line world: man pages and tldr pages.

man pages

First, let's take a look at man pages (short for manual pages). They are used in Unix based systems as documentation for command line tools. If you're using Linux or macos, you can try them by typing man tar to see the documentation for tar command.

Man pages are a good example of reference style documentation.

For tar, the man pages starts like this:

NAME
     tar -- manipulate tape archives

SYNOPSIS
     tar [bundled-flags <args>] [<file> | <pattern> ...]
     tar {-c} [options] [files | directories]
     tar {-r | -u} -f archive-file [options] [files | directories]
     tar {-t | -x} [options] [patterns]

DESCRIPTION
     tar creates and manipulates streaming archive files.  This implementation can extract from tar, pax, cpio, zip, jar, ar, xar, rpm, 7-zip, and ISO 9660 cdrom images and can create tar, pax, cpio, ar, zip, 7-zip, and shar archives.

Later, it'll list all the command line options and how to use them.

Man pages are very thorough but I find them often really difficult to read. When I was learning how to use unix-style systems and the commands, it wasn't uncommon to get the "just read the man pages" reply when asking for help. Honestly, that wasn't very helpful.

But as I've become more seasoned user of these tools, I often find myself opening up the man pages when I need to find some specific information about a flag.

tldr pages

On the recipe side, we have multiple different tools but the one I prefer to use these days is tldr pages. Their website says they "are a community effort to simplify the beloved man pages with practical examples."

Hence, they are the recipe cookbook for using the same tools that man pages provides reference documentation for.

For tar, the tldr pages starts like this:

tar

Archiving utility.
Often combined with a compression method, such as gzip or bzip2.
More information: <https://www.gnu.org/software/tar>.

- [c]reate an archive and write it to a [f]ile:
    tar cf target.tar file1 file2 file3

- [c]reate a g[z]ipped archive and write it to a [f]ile:
    tar czf target.tar.gz file1 file2 file3

- [c]reate a g[z]ipped archive from a directory using relative paths:
    tar czf target.tar.gz --directory=path/to/directory .

- E[x]tract a (compressed) archive [f]ile into the current directory [v]erbosely:
    tar xvf source.tar[.gz|.bz2|.xz]

Where man pages start from the completeness of reference, tldr pages start from practical needs. You don't need to know all the dozens of flags available, if you just need to create or extract an archive. I'd argue it's definitely more beginner-friendly too.

Recipe documentation is often community-driven like is in the case of aforementioned PHP documentation and in the case of tldr pages. And that's a great thing because then the examples come from real life use cases rather than the developer themselves trying to think of possible cases. It does however need a community large enough to be useful which can be a challenge for newer tools.

Which one should you use?

As an end user, you should use both. Learning how to read reference documentation of your tools, libraries and APIs is a skill that will always be useful and help you get the answers straight from the source material. But for many day-to-day operations, recipes are wonderful. Despite using tar for a few decades already, I still always use tldr tar when I need to create something because the interface isn't very intuitive to me – see xkcd 1168 for reference.

As a technical writer, I think the ultimate goal is to provide both. But documentation efforts often boil down to resource management and making a lot of compromises. Making it easy for the user community to submit recipes in a knowledge base is very valuable. Or, for example if you run a more chat-based community, actively collecting good recipes from discussions and sharing them via your documentation is something worth its weight in gold.

Last fall I ran into a great Twitter thread about documentation and recipes by Alec Barrett-Wilsdon. He wrote a lengthy thread about AWS documentation and his insights into how he would improve it to match the user needs better.