Exploring /usr/share/doc and tldr for LFCS Certification

Welcome to Part 14 of the LFCS Certification - Phase 1 series! You've mastered man pages, info pages, and --help. Now let's uncover the hidden treasure trove of documentation in /usr/share/doc and discover tldr for lightning-fast command examples.

Understanding /usr/share/doc

What is /usr/share/doc? A directory containing package-specific documentation installed alongside software packages on your Linux system.

Why /usr/share/doc Matters

Unlike man and info pages, /usr/share/doc contains:

• README files - Installation notes, usage tips, getting started guides
• Example configurations - Real working configuration file examples
• Changelogs - Version history and what changed between releases
• License files - Software licenses and legal information
• HOWTOs - Step-by-step guides for specific tasks
• Sample scripts - Actual code you can copy and modify
• NEWS files - Important announcements about the package

Structure of /usr/share/doc

Each installed package gets its own subdirectory:

/usr/share/doc/
├── bash-5.1.8/
│   ├── CHANGES
│   ├── COMPAT
│   ├── FAQ
│   ├── INTRO
│   ├── NEWS
│   └── README
├── openssh-8.7p1/
│   ├── CREDITS
│   ├── LICENCE
│   ├── OVERVIEW
│   ├── PROTOCOL
│   └── README
├── sudo-1.9.5/
│   ├── CONTRIBUTORS
│   ├── HISTORY
│   ├── LICENSE
│   ├── NEWS
│   └── README
└── ... (hundreds more)

Key Points:

• One directory per package
• Directory name usually includes version number
• Contains package-specific documentation files
• Files often compressed with gzip (.gz extension)

Exploring /usr/share/doc

Listing Installed Package Documentation

# List all package documentation directories
ls /usr/share/doc/

Example output:

acl-2.3.1        bash-5.1.8       coreutils-8.32   grep-3.6
audit-3.0.7      bind-license     cronie-1.5.7     gzip-1.10
bash-completion  ca-certificates  dnf-4.14.0       htop-3.2.1

What this shows:

• Each installed package with documentation
• Version numbers included in directory names
• Alphabetically sorted list

# Count how many packages have documentation
ls /usr/share/doc/ | wc -l

Example output:

437

Explanation:

• This system has documentation for 437 packages
• Not every installed package has /usr/share/doc entries
• Only packages that provide additional docs beyond man pages

Finding Specific Package Documentation

# Find documentation for packages matching "ssh"
ls /usr/share/doc/ | grep ssh

Example output:

openssh-8.7p1
openssh-clients-8.7p1
openssh-server-8.7p1

What this tells you:

• Three OpenSSH-related packages have documentation
• All are version 8.7p1
• Separate docs for client and server components

Viewing Package Documentation Contents

# See what's inside openssh documentation
ls /usr/share/doc/openssh-8.7p1/

Example output:

CREDITS  LICENCE  OVERVIEW  PROTOCOL  PROTOCOL.agent  PROTOCOL.certkeys  README

Files explained:

• CREDITS - Contributors and acknowledgments
• LICENCE - Legal terms (OpenSSH uses BSD license)
• OVERVIEW - High-level description of SSH architecture
• PROTOCOL* - Technical protocol specifications
• README - General information and getting started

Reading Documentation Files

# Read the README file
cat /usr/share/doc/openssh-8.7p1/README

Example output:

This is the README file for OpenSSH.

Please refer to the INSTALL file for installation instructions.

OpenSSH is a free implementation of the Secure Shell protocol suite,
providing encrypted communication sessions over a computer network.

For more information see:
  https://www.openssh.com/

Why this matters:

• Provides context about the package
• Links to more resources
• Often includes quick start guides
• May reference other doc files

Working with Compressed Documentation

Many documentation files are compressed with gzip to save disk space. You'll see .gz extensions.

Tools for Reading Compressed Files

Using zcat - View Compressed Files

# Find compressed documentation
ls /usr/share/doc/bash-5.1.8/

Example output:

CHANGES  COMPAT  FAQ  INTRO  NEWS  README

Let's say CHANGES is compressed:

# This won't work well - shows binary gibberish
cat /usr/share/doc/bash-5.1.8/CHANGES.gz

# Use zcat instead - decompresses and displays
zcat /usr/share/doc/bash-5.1.8/CHANGES.gz

How zcat works:

• Decompresses the .gz file on-the-fly
• Sends uncompressed content to stdout
• Original file remains compressed
• No temporary files created

Using zless - Page Through Compressed Files

# Page through a compressed changelog
zless /usr/share/doc/bash-5.1.8/CHANGES.gz

Navigation (same as less):

• Space - Next page
• b - Previous page
• /pattern - Search forward
• ?pattern - Search backward
• q - Quit

Why use zless?

• Long files are easier to read
• Can search within the file
• More comfortable than scrolling through zcat output

Using zgrep - Search Compressed Files

# Search for "security" in compressed changelog
zgrep -i security /usr/share/doc/bash-5.1.8/CHANGES.gz

Example output:

  - Fixed a security issue with array variable handling
  - Security patch for command injection vulnerability
  - Improved security of restricted shell mode

Command breakdown:

• zgrep - grep for compressed files
• -i - case-insensitive search
• security - pattern to search for
• .gz file - compressed documentation

Use cases:

• Finding security-related changes in changelogs
• Searching for specific features or bug fixes
• Locating configuration examples

Real-World Example: Finding Configuration Examples

Let's say you need to configure sudo and want to see examples:

# Step 1: Find sudo documentation
ls /usr/share/doc/ | grep sudo

Output:

sudo-1.9.5

# Step 2: Explore what's available
ls /usr/share/doc/sudo-1.9.5/

Output:

CONTRIBUTORS  examples/  HISTORY  LICENSE  NEWS  README  UPGRADE

Notice the examples/ directory!

# Step 3: See what examples exist
ls /usr/share/doc/sudo-1.9.5/examples/

Output:

pam.conf  sudo.conf  sudoers  syslog.conf

# Step 4: View an example sudoers file
cat /usr/share/doc/sudo-1.9.5/examples/sudoers

You'll see a working example sudoers configuration with:

• Commented explanations
• Best practice configurations
• Security recommendations
• Real-world scenarios

Introducing tldr - Too Long; Didn't Read

While man pages are comprehensive, sometimes you just want quick examples. That's where tldr comes in.

What is tldr?

tldr is a community-driven documentation project that provides simplified, example-focused help pages for common commands.

Philosophy:

• Show practical examples first
• Skip lengthy explanations
• Focus on common use cases
• Colorful, easy-to-scan format

Comparing man vs tldr

man ls (traditional):

LS(1)                     User Commands                    LS(1)

NAME
       ls - list directory contents

SYNOPSIS
       ls [OPTION]... [FILE]...

DESCRIPTION
       List  information  about  the FILEs (the current directory by
       default).  Sort entries alphabetically if none of -cftuvSUX nor
       --sort is specified.

       Mandatory arguments to long options are mandatory for short
       options too.

       -a, --all
              do not ignore entries starting with .

       -l     use a long listing format

       ... (hundreds more lines)

tldr ls (simplified):

ls
List directory contents.

- List files one per line:
  ls -1

- List all files, including hidden files:
  ls -a

- Long format list with permissions, ownership, size, and date:
  ls -la

- Long format with human-readable file sizes:
  ls -lh

- List files sorted by size (descending):
  ls -S

Key differences:

• tldr shows examples immediately
• man shows complete documentation
• tldr is faster for common tasks
• man is required for advanced options

Installing tldr

Method 1: npm (Node Package Manager)

# Install Node.js and npm first (if not installed)
sudo dnf install nodejs npm -y  # CentOS/RHEL
# OR
sudo apt install nodejs npm -y  # Ubuntu/Debian

# Install tldr globally
sudo npm install -g tldr

Verify installation:

tldr --version

Example output:

tldr 3.3.7

Method 2: Python pip

# Install Python pip first (if not installed)
sudo dnf install python3-pip -y  # CentOS/RHEL
# OR
sudo apt install python3-pip -y  # Ubuntu/Debian

# Install tldr
sudo pip3 install tldr

Method 3: Package Manager (if available)

# Some distributions have tldr in repositories
sudo dnf install tldr -y  # May not be available
# OR
sudo apt install tldr -y  # May not be available

Using tldr

Basic Usage

# Get quick examples for any command
tldr command_name

Example with tar:

tldr tar

Output:

tar
Archiving utility.

- Create an archive from files:
  tar cf target.tar file1 file2 file3

- Extract an archive:
  tar xf source.tar

- Create a gzipped archive:
  tar czf target.tar.gz file1 file2

- Extract a gzipped archive:
  tar xzf source.tar.gz

- List contents of an archive:
  tar tf source.tar

Why this is helpful:

• Shows the most common tar operations
• Includes the exact syntax
• No need to remember compression flags
• Covers 90% of daily use cases

Updating the tldr Database

# Update to get latest pages
tldr --update

When to update:

• After installing tldr for the first time
• Monthly or when you need newer docs
• When a command page seems outdated

Searching for Commands

# List all available pages
tldr --list

Output (partial):

7z
7za
ab
ack
acpi
adduser
...

# Search for specific topics
tldr --list | grep network

Building Your Documentation Strategy

Now that you know all four documentation methods, here's when to use each:

The Complete Documentation Workflow

Scenario: You need to use rsync but don't remember the syntax

Step 1: Quick examples (tldr)

tldr rsync

• Takes 5 seconds
• Shows common use cases
• Might be all you need

Step 2: If you need more (man page)

man rsync

• Complete option list
• Detailed explanations
• All edge cases covered

Step 3: For configuration files (man section 5)

man 5 rsync.conf  # if applicable

Step 4: For real examples (/usr/share/doc)

ls /usr/share/doc/rsync*/examples/

• Working configuration files
• Real-world scripts
• Copy and modify approach

Comparison Table: All Documentation Methods

🧪 Practice Labs

Time to practice! These labs will help you master /usr/share/doc and tldr.

sudo dnf install bash-completion httpd nginx -y  # CentOS/RHEL
# OR
sudo apt install bash-completion apache2 nginx -y  # Ubuntu/Debian

Lab 1: Exploring /usr/share/doc (Beginner)

Task 1.1: List all package documentation on your system

ls /usr/share/doc/

[centos9@centos ~]$ ls /usr/share/doc/
acl-2.3.1  bash-5.1.8  coreutils-8.32  grep-3.6  openssh-8.7p1  sudo-1.9.5

Task 1.2: Count how many packages have documentation

ls /usr/share/doc/ | wc -l

[centos9@centos ~]$ ls /usr/share/doc/ | wc -l
437

Task 1.3: Find all packages related to "network"

ls /usr/share/doc/ | grep -i network

[centos9@centos ~]$ ls /usr/share/doc/ | grep -i network
NetworkManager-1.36.0
network-scripts-10.11

Lab 2: Reading Documentation Files (Beginner)

Task 2.1: Explore what documentation bash provides

ls /usr/share/doc/bash*/

[centos9@centos ~]$ ls /usr/share/doc/bash-5.1.8/
CHANGES  COMPAT  FAQ  INTRO  NEWS  README

Task 2.2: Read the bash README file

cat /usr/share/doc/bash*/README

[centos9@centos ~]$ cat /usr/share/doc/bash-5.1.8/README
Introduction
============

This is GNU bash, version 5.1.  Bash is the GNU Project's Bourne
Again SHell, a complete implementation of the POSIX shell spec...

Task 2.3: View the bash FAQ (using less for paging)

less /usr/share/doc/bash*/FAQ

[centos9@centos ~]$ less /usr/share/doc/bash-5.1.8/FAQ

Lab 3: Working with Compressed Documentation (Intermediate)

Task 3.1: Find compressed files in documentation

find /usr/share/doc/bash*/ -name "*.gz"

[centos9@centos ~]$ find /usr/share/doc/bash-5.1.8/ -name "*.gz"
/usr/share/doc/bash-5.1.8/CHANGES.gz
/usr/share/doc/bash-5.1.8/NEWS.gz

Task 3.2: View compressed CHANGES file with zcat

zcat /usr/share/doc/bash*/CHANGES.gz | head -20

[centos9@centos ~]$ zcat /usr/share/doc/bash-5.1.8/CHANGES.gz | head -20
This document details the changes between this version, bash-5.1,
and the previous version, bash-5.0.

1. Changes to Bash

a. Fixed a bug that caused the SIGINT handler to be removed when in a
   background job that exited, which prevented the parent shell from
   handling SIGINT.
...

Task 3.3: Page through compressed file with zless

zless /usr/share/doc/bash*/CHANGES.gz

Task 3.4: Search for "security" in compressed changelog

zgrep -i "security" /usr/share/doc/bash*/CHANGES.gz

[centos9@centos ~]$ zgrep -i "security" /usr/share/doc/bash-5.1.8/CHANGES.gz
a. Fixed a security issue with array variable handling
b. Security patch for command injection vulnerability

Lab 4: Finding Configuration Examples (Intermediate)

Task 4.1: Check if openssh has example configurations

ls /usr/share/doc/openssh*/

[centos9@centos ~]$ ls /usr/share/doc/openssh-8.7p1/
CREDITS  LICENCE  OVERVIEW  PROTOCOL  PROTOCOL.agent  README

Task 4.2: Find packages that have examples directories

find /usr/share/doc/ -type d -name "examples" | head -10

[centos9@centos ~]$ find /usr/share/doc/ -type d -name "examples" | head -10
/usr/share/doc/sudo-1.9.5/examples
/usr/share/doc/logrotate-3.18.0/examples
/usr/share/doc/rsyslog-8.2102.0/examples
/usr/share/doc/httpd-2.4.51/examples

Task 4.3: Explore sudo examples

ls /usr/share/doc/sudo*/examples/

[centos9@centos ~]$ ls /usr/share/doc/sudo-1.9.5/examples/
pam.conf  sudo.conf  sudoers  syslog.conf

Task 4.4: View the example sudoers file

cat /usr/share/doc/sudo*/examples/sudoers | head -30

[centos9@centos ~]$ cat /usr/share/doc/sudo-1.9.5/examples/sudoers | head -30
##
## Sample sudoers file
##
## This file MUST be edited with the 'visudo' command as root.
##
## See the man page for details on how to write a sudoers file.
##

##
## Host alias specification
##
## Groups of machines...

Lab 5: Installing and Using tldr (Intermediate)

Task 5.1: Install tldr using npm (if not already installed)

# Install Node.js and npm first
sudo dnf install nodejs npm -y

# Install tldr globally
sudo npm install -g tldr

[centos9@centos ~]$ sudo dnf install nodejs npm -y
Last metadata expiration check: 0:05:23 ago on Tue 05 Nov 2025.
Dependencies resolved.
===========================================
 Package       Arch    Version    Repository   Size
===========================================
Installing:
 nodejs        x86_64  16.14.0    appstream    12 M
 npm           x86_64  8.3.1      appstream    2.1 M
...

[centos9@centos ~]$ sudo npm install -g tldr
/usr/bin/tldr -> /usr/lib/node_modules/tldr/bin/tldr
+ tldr@3.3.7
added 35 packages in 3.821s

tldr --version

Task 5.2: Get quick examples for the tar command

tldr tar

[centos9@centos ~]$ tldr tar

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

  - Create an archive from files:
    tar cf target.tar file1 file2 file3

  - Create a gzipped archive:
    tar czf target.tar.gz file1 file2 file3

  - Extract an archive:
    tar xf source.tar

  - Extract a gzipped archive:
    tar xzf source.tar.gz

  - Extract an archive to a specific directory:
    tar xf source.tar -C /path/to/directory

  - List the contents of a tar file:
    tar tf source.tar

Task 5.3: Compare tldr vs man for the find command

# First try tldr
tldr find

# Then compare with man
man find

find
Find files or directories under the given directory tree, recursively.

- Find files by extension:
  find root_path -name '*.ext'

- Find files by matching multiple patterns:
  find root_path -name '*pattern_1*' -or -name '*pattern_2*'

- Find directories:
  find root_path -type d

- Find files modified in the last 7 days:
  find root_path -mtime -7

Task 5.4: Update tldr database

tldr --update

[centos9@centos ~]$ tldr --update
✓ Successfully updated cache

Lab 6: Documentation Detective Work (Advanced)

Task 6.1: Find documentation for the package that provides SELinux tools

# Find selinux related packages
ls /usr/share/doc/ | grep -i selinux

[centos9@centos ~]$ ls /usr/share/doc/ | grep -i selinux
libselinux-3.3
libselinux-utils-3.3
selinux-policy-3.14.3
selinux-policy-targeted-3.14.3

Task 6.2: Find which package has the most documentation files

for dir in /usr/share/doc/*/; do
  echo -n "$(basename "$dir"): "
  find "$dir" -type f | wc -l
done | sort -t: -k2 -nr | head -5

[centos9@centos ~]$ for dir in /usr/share/doc/*/; do
  echo -n "$(basename "$dir"): "
  find "$dir" -type f | wc -l
done | sort -t: -k2 -nr | head -5

httpd-2.4.51: 127
kernel-5.14.0: 89
selinux-policy-targeted-3.14.3: 67
python3-3.9.9: 45
bash-5.1.8: 23

Task 6.3: Find all README files in /usr/share/doc

find /usr/share/doc/ -name "README*" -type f | wc -l

[centos9@centos ~]$ find /usr/share/doc/ -name "README*" -type f | wc -l
312

find /usr/share/doc/ -name "README*" -type f | head -10

Lab 7: Building Documentation Workflows (Advanced)

Task 7.1: Create a workflow to learn about the rsync command

# Step 1: Quick examples with tldr
tldr rsync

# Step 2: If you need more, check man page
man rsync

# Step 3: Look for configuration examples
ls /usr/share/doc/rsync*/examples/ 2>/dev/null

# Step 4: Read any README
cat /usr/share/doc/rsync*/README* 2>/dev/null | head -20

rsync
Transfer files to or from a remote host (but not between two remote hosts).

- Transfer a file:
  rsync path/to/source path/to/destination

- Transfer with archive mode (preserves permissions, ownership, etc.):
  rsync -a path/to/source path/to/destination

- Transfer with compression:
  rsync -az path/to/source path/to/destination

ls /usr/share/doc/rsync*/examples/
# May or may not exist

cat /usr/share/doc/rsync*/README

Task 7.2: Document your findings about the systemd package

# Explore systemd documentation
ls /usr/share/doc/systemd*/

[centos9@centos ~]$ ls /usr/share/doc/systemd-250/
20-yama-ptrace.conf  CODING_STYLE  LICENSE.GPL2  NEWS  README  UIDS-GIDS.md

# Start with README
cat /usr/share/doc/systemd-250/README

# Check recent changes
less /usr/share/doc/systemd-250/NEWS

# Learn about UID/GID conventions
cat /usr/share/doc/systemd-250/UIDS-GIDS.md

Lab 8: Compressed File Operations (Advanced)

Task 8.1: Find the 5 largest compressed documentation files

find /usr/share/doc/ -name "*.gz" -type f -exec ls -lh {} \; | sort -k5 -hr | head -5

[centos9@centos ~]$ find /usr/share/doc/ -name "*.gz" -type f -exec ls -lh {} \; | sort -k5 -hr | head -5
-rw-r--r--. 1 root root 1.2M Oct 15 10:23 /usr/share/doc/bash-5.1.8/CHANGES.gz
-rw-r--r--. 1 root root 856K Oct 15 10:23 /usr/share/doc/systemd-250/NEWS.gz
-rw-r--r--. 1 root root 432K Oct 12 09:15 /usr/share/doc/kernel-5.14.0/changelog.gz
-rw-r--r--. 1 root root 287K Oct 10 11:45 /usr/share/doc/python3-3.9.9/NEWS.gz
-rw-r--r--. 1 root root 156K Sep 28 14:32 /usr/share/doc/httpd-2.4.51/CHANGES.gz

Task 8.2: Compare compressed vs uncompressed size

# Check compressed size
ls -lh /usr/share/doc/bash*/CHANGES.gz

# Check uncompressed size
zcat /usr/share/doc/bash*/CHANGES.gz | wc -c | numfmt --to=iec

[centos9@centos ~]$ ls -lh /usr/share/doc/bash-5.1.8/CHANGES.gz
-rw-r--r--. 1 root root 1.2M Oct 15 10:23 /usr/share/doc/bash-5.1.8/CHANGES.gz

[centos9@centos ~]$ zcat /usr/share/doc/bash-5.1.8/CHANGES.gz | wc -c | numfmt --to=iec
5.8M

Task 8.3: Search all compressed changelogs for "CVE" (security vulnerabilities)

find /usr/share/doc/ -name "*CHANGE*.gz" -exec zgrep -l "CVE" {} \;

[centos9@centos ~]$ find /usr/share/doc/ -name "*CHANGE*.gz" -exec zgrep -l "CVE" {} \;
/usr/share/doc/bash-5.1.8/CHANGES.gz
/usr/share/doc/openssh-8.7p1/CHANGES.gz
/usr/share/doc/sudo-1.9.5/CHANGES.gz

zgrep "CVE" /usr/share/doc/bash-5.1.8/CHANGES.gz

Lab 9: Real-World Scenarios (Advanced)

Task 9.1: You need to configure Apache httpd. Find example configurations.

# Step 1: Find httpd documentation
ls /usr/share/doc/ | grep httpd

# Step 2: Check for examples
ls /usr/share/doc/httpd*/

# Step 3: Look for config examples
find /usr/share/doc/httpd*/ -name "*.conf*"

[centos9@centos ~]$ ls /usr/share/doc/ | grep httpd
httpd-2.4.51

[centos9@centos ~]$ ls /usr/share/doc/httpd-2.4.51/
ABOUT_APACHE  CHANGES  httpd-manual/  LICENSE  NOTICE  README  VERSIONING

[centos9@centos ~]$ find /usr/share/doc/httpd-2.4.51/ -name "*.conf*"
# Results will vary, but look for example configs

Task 9.2: You're debugging SSH issues. Find SSH protocol documentation.

# Find OpenSSH docs
ls /usr/share/doc/openssh*/

# Read protocol documentation
cat /usr/share/doc/openssh*/PROTOCOL | head -50

[centos9@centos ~]$ ls /usr/share/doc/openssh-8.7p1/
CREDITS  LICENCE  OVERVIEW  PROTOCOL  PROTOCOL.agent  PROTOCOL.certkeys  README

[centos9@centos ~]$ cat /usr/share/doc/openssh-8.7p1/PROTOCOL | head -50
This documents OpenSSH's deviations and extensions to the published SSH
protocol.

OpenSSH implements the following SSH protocol versions:

SSH protocol version 1 (no longer supported)
SSH protocol version 2 (supported)

...

Task 9.3: You need to understand logrotate. Build complete documentation picture.

# Step 1: Quick examples
tldr logrotate

# Step 2: Find examples
ls /usr/share/doc/logrotate*/examples/

# Step 3: View man page for complete reference
man logrotate

# Step 4: Check README
cat /usr/share/doc/logrotate*/README*

logrotate
Rotates, compresses, and mails system logs.

- Trigger a run manually:
  logrotate /etc/logrotate.conf

- Run with verbose output:
  logrotate -v /etc/logrotate.conf

- Dry run (test without making changes):
  logrotate -d /etc/logrotate.conf

ls /usr/share/doc/logrotate-3.18.0/examples/
# Should show example config files

man logrotate
# Complete reference: all options, rotation strategies, compression methods

cat /usr/share/doc/logrotate-3.18.0/README
# Context: what logrotate does, why it exists, basic usage

Lab 10: Creating Your Documentation Library (Challenge)

Task 10.1: Create a personal reference of the most useful package documentation

# Create a documentation directory
mkdir -p ~/lfcs-docs

# Copy important READMEs
for pkg in bash sudo openssh systemd; do
  find /usr/share/doc/ -name "$pkg*" -type d -exec cp {}/README ~/lfcs-docs/README-$pkg 2>/dev/null \;
done

# List your collection
ls -lh ~/lfcs-docs/

[centos9@centos ~]$ mkdir -p ~/lfcs-docs

[centos9@centos ~]$ for pkg in bash sudo openssh systemd; do
  find /usr/share/doc/ -name "$pkg*" -type d -exec cp {}/README ~/lfcs-docs/README-$pkg 2>/dev/null \;
done

[centos9@centos ~]$ ls -lh ~/lfcs-docs/
total 48K
-rw-r--r--. 1 centos9 centos9 3.2K Nov 05 14:23 README-bash
-rw-r--r--. 1 centos9 centos9 5.1K Nov 05 14:23 README-openssh
-rw-r--r--. 1 centos9 centos9 2.8K Nov 05 14:23 README-sudo
-rw-r--r--. 1 centos9 centos9 4.5K Nov 05 14:23 README-systemd

# Add more packages
for pkg in httpd nginx postgresql; do
  find /usr/share/doc/ -name "$pkg*" -type d -exec cp {}/README ~/lfcs-docs/README-$pkg 2>/dev/null \;
done

📚 Best Practices

Documentation Hierarchy for LFCS

1. Start with tldr (30 seconds)

• Quick command examples
• Common use cases covered
• Fast syntax reminder

2. Use --help for quick reference (10 seconds)

• Brief option list
• Quick reminder of flags
• No navigation needed

3. Check /usr/share/doc for examples (2 minutes)

• Working configuration files
• Real-world scripts
• Package-specific details

4. Deep dive with man pages (5-15 minutes)

• Complete option reference
• All edge cases
• Detailed explanations

5. Tutorial mode with info (15-30 minutes)

• Comprehensive guides
• GNU tool tutorials
• Interactive learning

When Configuring New Services

Step 1: Check for examples first

ls /usr/share/doc/package-name*/examples/

Step 2: Read the README

cat /usr/share/doc/package-name*/README

Step 3: Copy example, don't start from scratch

cp /usr/share/doc/package-name/examples/config.conf /etc/package-name/

Step 4: Modify the example

vim /etc/package-name/config.conf

Step 5: Check man page for specific options

man 5 config-file-name  # Section 5 for config files

For LFCS Exam

Time-saving strategies:

1. Memorize common /usr/share/doc locations

   • /usr/share/doc/sudo*/examples/sudoers
   • /usr/share/doc/openssh*/README
   • /usr/share/doc/httpd*/README

2. Use z tools confidently*

   • zless for reading long changelogs
   • zgrep for finding specific info
   • zcat | head for previewing

3. Combine with man pages

   • Example from /usr/share/doc
   • Option details from man page
   • Best of both worlds

4. Create quick aliases (practice system)

   alias doc='cd /usr/share/doc && ls'
   alias docgrep='ls /usr/share/doc | grep'
   

   Copy

Documentation Maintenance

Keep documentation current:

# Update tldr database monthly
tldr --update

# Check for new documentation after package updates
sudo dnf update -y
ls -lt /usr/share/doc/ | head -10  # See recently updated docs

Create documentation notes:

# Personal notes directory
mkdir -p ~/docs-notes

# Add notes as you learn
echo "rsync -avz for archive + verbose + compression" >> ~/docs-notes/rsync-tips.txt

🚨 Common Pitfalls to Avoid

Pitfall 1: Ignoring /usr/share/doc Entirely

Problem: Many sysadmins never explore /usr/share/doc, missing valuable examples.

Solution: Make it a habit. When installing a new package, immediately check:

ls /usr/share/doc/package-name*/

Pitfall 2: Forgetting to Use z* Tools

Problem: Trying to read compressed files directly:

cat /usr/share/doc/bash-5.1.8/CHANGES.gz  # Shows gibberish!

Solution: Use the z-prefixed versions:

zcat /usr/share/doc/bash-5.1.8/CHANGES.gz  # Works perfectly!

Pitfall 3: Assuming tldr is Always Available

Problem: Relying on tldr during LFCS exam (it won't be installed).

Solution:

• Use tldr for practice and learning
• Know how to use man pages for the exam
• Practice both methods

Pitfall 4: Not Reading READMEs First

Problem: Diving into complex docs without context.

Solution: Always start with README:

cat /usr/share/doc/package-name*/README | less

It provides context that makes other docs make sense.

Pitfall 5: Copying Examples Without Understanding

Problem: Copying example configs blindly without understanding.

Solution:

1. Copy the example
2. Read comments in the file
3. Check man page for options you don't understand
4. Test incrementally

Pitfall 6: Forgetting Documentation Versions

Problem: Looking at old documentation for updated software.

Solution: Always check version numbers:

ls -l /usr/share/doc/ | grep package-name
# Version number is in directory name

📝 Command Cheat Sheet

/usr/share/doc Commands

# List all package documentation
ls /usr/share/doc/

# Count documentation packages
ls /usr/share/doc/ | wc -l

# Find specific package docs
ls /usr/share/doc/ | grep package-name

# Explore package documentation
ls /usr/share/doc/package-name*/

# Read documentation file
cat /usr/share/doc/package-name*/README

# Find example directories
find /usr/share/doc/ -type d -name "examples"

# List examples for specific package
ls /usr/share/doc/package-name*/examples/

Compressed File Commands

# View compressed file
zcat file.gz

# Page through compressed file
zless file.gz

# Search compressed file
zgrep pattern file.gz

# Search case-insensitive
zgrep -i pattern file.gz

# Count lines in compressed file
zcat file.gz | wc -l

# Show first 20 lines of compressed file
zcat file.gz | head -20

# Compare compressed files
zdiff file1.gz file2.gz

tldr Commands

# Install tldr (npm method)
sudo npm install -g tldr

# Install tldr (pip method)
sudo pip3 install tldr

# Get examples for command
tldr command-name

# Update tldr database
tldr --update

# List all available pages
tldr --list

# Search for command
tldr --list | grep keyword

# Show version
tldr --version

Combined Workflows

# Find and view compressed changelogs
find /usr/share/doc/ -name "CHANGE*.gz" | head -5 | xargs zless

# Search all READMEs for keyword
find /usr/share/doc/ -name "README*" -exec grep -l "keyword" {} \;

# Count total documentation files
find /usr/share/doc/ -type f | wc -l

# Find largest documentation files
find /usr/share/doc/ -type f -exec ls -lh {} \; | sort -k5 -hr | head -10

🎯 Key Takeaways

Let's summarize what you've mastered:

About /usr/share/doc:

• Package-specific documentation directory
• Contains READMEs, examples, changelogs, licenses
• Each package gets its own subdirectory
• Often includes working configuration examples
• Many files are gzip-compressed

About z Tools:*

• zcat - view compressed files
• zless - page through compressed files
• zgrep - search compressed files
• All work like their non-z counterparts
• No need to decompress files manually

About tldr:

• Community-driven simplified documentation
• Focuses on practical examples
• Faster than man pages for common tasks
• Install with npm or pip
• NOT available during LFCS exam (but great for learning)

Documentation Strategy:

1. tldr → Quick examples (practice only)
2. --help → Brief option list
3. /usr/share/doc → Configuration examples
4. man pages → Complete reference (exam)
5. info pages → Comprehensive tutorials

For LFCS Success:

• Practice with all methods
• Know where to find examples
• Master z* tools for compressed docs
• Create your own documentation library
• Use man + /usr/share/doc during exam

🚀 What's Next?

In Part 15, we'll move on to a completely new topic: Understanding Network Interfaces with the ip Command. You'll learn:

• Network interface basics (what is eth0, lo, etc.)
• Using ip addr to view IP addresses
• Using ip link to manage interfaces
• Understanding interface states (UP, DOWN)
• Temporary vs permanent network configuration
• And much more!

Recommended practice before next post:

• Work through all 20 practice labs above
• Install tldr and try it on 10 different commands
• Explore /usr/share/doc for packages you use daily
• Create your personal documentation library
• Practice combining methods (tldr → man → examples)

Continue your LFCS journey:

• Previous: Part 13 - Using info, pinfo, and --help
• Next: Part 15 - Understanding Network Interfaces with ip Command