Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

README: add table of contents, installation methods, and troubleshooting & FAQ sections #15770

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

README: add table of contents, installation methods, and troubleshooting & FAQ sections #15770

wants to merge 2 commits into from
+27 −0

Conversation

ShreyasKodela
Copy link

Summary:

This PR enhances the README.md file by improving its structure and clarity. The key updates include:

  • Added a Table of Contents to improve navigation.
  • Refactored the Installation section into a table for easier readability.
  • Expanded the Troubleshooting & FAQ section to help users quickly resolve common issues.

Changes:

  • Table of Contents:
    • Added a structured and hyperlinked list for easier access to different sections and improved navigation.
  • Installation Methods:
    • Converted the most common installation instructions into a comparison table.
    • Made it easier to distinguish between Node.js, Python, and Rust installation methods.
  • Troubleshooting & FAQ Section:
    • Added questions that need to be filled in by owners or frequent contributors for common issues like:
      • tldr command not found.
      • Updating tldr pages.
      • Using tldr offline.
    • Helps provide step-by-step troubleshooting instructions for users facing installation issues.

Why this change?

  • Improves readability and ease of navigation within the README.
  • Helps new users quickly find relevant information without searching through long text sections.
  • Reduces frequently asked questions by providing easy troubleshooting steps.

@CLAassistant
Copy link

CLA assistant check
Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you sign our Contributor License Agreement before we can accept your contribution.
You have signed the CLA already but the status is still pending? Let us recheck it.

@github-actions github-actions bot added the documentation Issues/PRs modifying the documentation. label Feb 21, 2025
sebastiaanspeck
sebastiaanspeck requested changes Feb 22, 2025
View reviewed changes
README.md
Comment on lines +180 to +184
### **Q: I installed `tldr`, but the command is not recognized. What should I do?**

### **Q: How do I update my tldr pages?**

### **Q: Can I use tldr offline?**
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please answer the questions as well.

@Managor Managor changed the title Enhance README: Adding Table of Contents, Installation Methods, and Troubleshooting & FAQ sections README: add table of contents, installation methods, and troubleshooting & FAQ sections Feb 23, 2025
gutjuri
gutjuri reviewed Feb 23, 2025
View reviewed changes
Copy link
Member

@gutjuri gutjuri left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thank you for your contribution and efforts. However, I would be against adding a TOC and the Installation methods sections for the reasons explained below. Making the Q&A section more exhaustive is certainly a good idea.

README.md
Comment on lines +108 to +116
## Installation Methods
| Client | Installation Command | Package Manager |
|--------|----------------------|----------------|
| **Node.js Client** | `npm install -g tldr` | npm |
| **Python Client** | `pip3 install tldr` | pip |
| **Rust Client** | `brew install tlrc` | Homebrew |

For alternative installation methods, check out our [Wiki](https://github.com/tldr-pages/tldr/wiki/Clients).

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This section is basically the same as the previous one. Why should this be added in your opinion?

README.md
Comment on lines +27 to +35
## Table of Contents

- [What is tldr-pages?](#what-is-tldr-pages)
- [How do I use it?](#how-do-i-use-it)
- [Installation Methods](#installation-methods)
- [How do I contribute to tldr-pages?](#how-do-i-contribute-to-tldr-pages)
- [Similar projects](#similar-projects)
- [Troubleshooting & FAQ](#troubleshooting--faq)
- [What does "tldr" mean?](#what-does-tldr-mean)
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

image

A table of contents is automatically generated by the Github UI

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@gutjuri gutjuri gutjuri left review comments

@sebastiaanspeck sebastiaanspeck sebastiaanspeck requested changes

@sbrl sbrl Awaiting requested review from sbrl sbrl is a code owner

@kbdharun kbdharun Awaiting requested review from kbdharun kbdharun is a code owner

Requested changes must be addressed to merge this pull request.

Assignees
No one assigned
Labels
documentation Issues/PRs modifying the documentation.
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
4 participants
@ShreyasKodela @CLAassistant @sebastiaanspeck @gutjuri