From 45e4b3b6433eb9ae2815ab9aea236f8f20f7bc57 Mon Sep 17 00:00:00 2001 From: M_with_Heart Date: Sun, 28 Sep 2025 13:11:03 +0100 Subject: [PATCH 1/3] Review for tldr-pages --- docs/2025/reviews/tldr-pages-review.md | 100 +++++++++++++++++++++++++ 1 file changed, 100 insertions(+) create mode 100644 docs/2025/reviews/tldr-pages-review.md diff --git a/docs/2025/reviews/tldr-pages-review.md b/docs/2025/reviews/tldr-pages-review.md new file mode 100644 index 0000000..30f399b --- /dev/null +++ b/docs/2025/reviews/tldr-pages-review.md @@ -0,0 +1,100 @@ +# Technical documentation review template + +## Documentation title: +[tldr-pages](https://github.com/tldr-pages/tldr/tree/main) repository. + +**Create new branch** + +## Reviewer information: +- **Name**: Mariam Yusuff +- **Date of Review**: Spet. 26, 20256/09/2025 +- **Review Level**: Intermediate + +## 1. Summary: +*tldr-pages* is a community-maintained collection of short, example-based cheat-sheets for CLI commands. *tldr* focuses on practical examples which help with learning. It is a compact complement to *man* pages. + +*Man* pages are the original documentations for UNIX and UNIX-like commands. However, these pages are often dense with lots of technical jargons. + + +The *tldr-pages* documentation explains: + - The purpose of the project. + - How contributors can add or improve pages. + - Style and formatting rules for writing code pages. + - Developer-specific guidelines such as linting and client-specification. + + + +## 2. Clarity and comprehensiveness: + +**Balance** +- The language is friendly and README.md provides useful links for beginners to check. +- CONTRIBUTING.md outlines the process of adding and editing pages. +- The style guide explains the page format with good examples. +- The documentation covers key areas including: + - The purpose of the project. + - Clear explanation of the pages and their purpose. + - How clients fetch pages. + - The contribution workflow: fork, clone, PR. +- The code pages are easy to scan through and understand. + +**Gaps** +- Some sections assume prior Git and GitHub knowledge, which may not be true in all cases. +- CONTRIBUTING.md has numerous hyperlinks. This can cause users to jump around. +- CONTRIBUTING.md is too dense and contributors may not read the whole of it, which defeats its purpose. +- Some technical jargons such as “lint CI fails”, “autogenerated index” are not clearly explained. + + + + +## 3. Accuracy and relevance: +- Details such as the file structure and naming rules seem correct and align with the repository’s implementation. +- The repo follows best practices for open source contribution. For example, linking to GitHub help, PR templates. + +**Caution** +- There should be periodic review to ensure installation examples are not outdated. +- The repo can align better with modern technical writing practices. + + +## 4. Structure and organization: +- There is clear separation of documents: README, CONTRIBUTING, Style guide, Client specification. + +**Gaps** +- Fist time contributors may not know where to start as CONTRIBUTING.md is dense and has numerous links. +- There is no table of contents in CONTRIBUTING.md. +- Some sequential guides are scattered across multiple files. + + + + +## 5. Visual and design elements: +- There are no diagrams or screenshots. + +- Consistent markdown formatting, but some sections are long walls of text. + + + +## 6. Suggestions for improvement: +- A quickstart guide for beginners. Something like a "Make your first PR in 10 minutes" page. It can cover points such as: + - Forking, cloning, and creating a branch. + - Running `tldr-lint` locally to catch errors early. + - Checklist to go through before creating a PR. + +- A table of contents in CONTRIBUTING.md. +- A "Start here" section to guide newcomers. +- Diagrams showing the folder structure. +- A troubleshooting section for common PR failures. +- The commands in the code pages should be indented. This allows for easier scanning and comprehension, especially for new users. + + + +## 7. Notable strengths: +- The code pages are brief and straightforward. This helps with scanning. +- The friendly tone encourages contribution. +- The repo is well-structured which makes navigation once you understand the folder names. + + +## 8. Overall assessment: +Rating: 4/5 +The documentation is strong, but could be better for onboarding absolute beginners. +It has a clear style guide and community-first tone. However, it lacks a single “follow-this-exactly” quickstart guide. + From 8d38fbcbd03af9cd8be742123fa8d91106e66797 Mon Sep 17 00:00:00 2001 From: Yusuff Mariam Date: Wed, 1 Oct 2025 11:36:26 +0100 Subject: [PATCH 2/3] Update tldr-pages-review.md --- docs/2025/reviews/tldr-pages-review.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/2025/reviews/tldr-pages-review.md b/docs/2025/reviews/tldr-pages-review.md index 30f399b..d3d23b0 100644 --- a/docs/2025/reviews/tldr-pages-review.md +++ b/docs/2025/reviews/tldr-pages-review.md @@ -1,4 +1,4 @@ -# Technical documentation review template +# Technical documentation review ## Documentation title: [tldr-pages](https://github.com/tldr-pages/tldr/tree/main) repository. From 425369f644ba790ac9c855109db837bdd071cbe0 Mon Sep 17 00:00:00 2001 From: Yusuff Mariam Date: Wed, 1 Oct 2025 11:45:54 +0100 Subject: [PATCH 3/3] Update tldr-pages-review.md Edited the first H2 --- docs/2025/reviews/tldr-pages-review.md | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/2025/reviews/tldr-pages-review.md b/docs/2025/reviews/tldr-pages-review.md index d3d23b0..c793d47 100644 --- a/docs/2025/reviews/tldr-pages-review.md +++ b/docs/2025/reviews/tldr-pages-review.md @@ -1,9 +1,6 @@ # Technical documentation review -## Documentation title: -[tldr-pages](https://github.com/tldr-pages/tldr/tree/main) repository. - -**Create new branch** +**Reviewed Documentation:** [tldr-pages](https://github.com/tldr-pages/tldr/tree/main) repository. ## Reviewer information: - **Name**: Mariam Yusuff