This article was published on November 24, 2017

TLDR is what Linux man pages always should have been


TLDR is what Linux man pages always should have been

If you get stuck using a Linux tool, the first port of call shouldn’t be to Stack Overflow, but rather its “man pages.” Man — which is short for manual — retrieves documentation for a given program. Unfortunately, this can often be dense, hard to understand, and lacking in practical examples to help you solve your problem.

TLDR is another way of looking at documentation. Rather than being a comprehensive guide to a given tool, it instead focuses on offering practical example-driven instructions of how something works.

Take wget, for example. This is a tool used for downloading files from the Internet. For such a straightforward and everyday Unix utility, wget has a weirdly long and complicated man page. Nor only does this offer a detailed description of what it does, it also exhaustively lists its many commands — many of which are seldom used.

TLDR, on the other hand, sums it up in a couple of sentences (“Download files from the Web. Supports HTTP, HTTPS, and FTP.”) and offers a few examples of how to use it, based on real-life scenarios you’re likely to encounter at some point: like downloading a webpage with all of its assets, or retrieving the contents of an FTP folder.

For those pressed for time, TLDR is awesome. I wouldn’t depend on it completely though, as for some apps, documentation is extremely patchy.

The TLDR page for Git, for example, covered almost nothing on how to use it, save how to check the version, and how to bring up the Git help pages. And some tools don’t have any documentation whatsoever; although that’s to be expected when you consider that this is an unofficial third-party effort.

These flaws are easily forgiven, especially when you consider that in many cases, it could save you a trip to Google to figure out how something works. For 99 percent of people who just need to figure out some syntax, and don’t actually want to get trapped in a quagmire of superfluous information, TLDR is excellent. While it will never truly replace man pages, it compliments them nicely.

If you’re curious, you can check out the TLDR project website here. This contains installation instructions, and information on how to contribute, should you be so inclined.

Get the TNW newsletter

Get the most important tech news in your inbox each week.

Published
Back to top