tldr-pages / tldr-pages/tldr-python-client

Update the database *after* printing

Open
#197 3 comments 4 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
749
Forks
117
PR merge metrics
No merged PRs in 30d

Description

The tldr client frequently wants to update pages, which requires a network request, which takes a few seconds. This seems to me like not ideal UX for a quick reference tool. When I'm trying to look up some basic syntax of a command, giving an answer quickly is more important than giving a definitive one - if I want the definitive, I'd be looking at the man page or searching on the internet instead of using tldr.

From what I can tell, the current flow is:

  1. User requests page of topic
  2. tldr checks cache, maybe updates the page
  3. tldr shows the page

I think a better UX would be:

  1. User requests page of topic
  2. If page is present in the cache:
    1. tldr shows it
    2. tldr updates the page (if cache is stale)
    3. If the new version is actually different, tldr prints a message: "This page has been changed from the one you just saw. Run tldr again to see the new version."
  3. If page is not present in the cache at all:
    1. tldr prints a message: "Hold on, fetching page from the database..."
    2. tldr updates the page
    3. tldr shows it

This is of course more complex, but I think justified by the benefit to the user. What do you think? I'm willing to author a PR if the idea sounds reasonable.

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

The issue names no files, tests, or entry points. Start by tracing the Python CLI's cache lookup, page rendering, and update flow; compare the current sequence with the proposed cached and uncached cases. Done means cached pages print promptly, stale updates happen afterward, changed pages are reported, and uncached pages show the fetch message before rendering.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
cli
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.