tortoise / tortoise/tortoise-orm

Documentation: Confusing graph

Open
#585 1 comment 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Python
Stars
5.6k
Forks
516
Avg merge
2d 21h
Merged PRs (30d)
9

Description

Describe the bug
I just looked at the front page of this package's github. I glanced at the readme, and I saw a graph. It compares different ORM's to Tortose. The graph itself doesn't appear erroneous, but the y-axis isn't labelled, and there's no surrounding explanation of what's being compared. Is performance is clock cycles? Nanoseconds? I am not sure if lower is better, or higher is better. I appreciate it seems to be an objective comparison across different ORM's, but I don't know what performance metric you are benchmarking against.

I won't discount your package based on something so small, but as someone who works with data in an analytics capacity, this damages credibility from what otherwise seems like a fantastic tool.

To Reproduce
Check your front page Readme.

Expected behavior
A labelled y-axis which indicates your performance metric, or an edit on the sentence above explaining what the y-axis intends to measure.

Additional context
I skimmed https://github.com/tortoise/orm-benchmarks and while there's a lot of raw data, I still am left unsure about how to interpret these results. I think it's a good idea to include these things, but a small explanation about what they mean can help outside people who are curious about this project.

Contributor guide

Open the contributing guide

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

Inspect the graph on the project's front-page README and compare it with the raw data in https://github.com/tortoise/orm-benchmarks. Determine which performance metric and direction the graph uses, then update the README with a labelled y-axis or a concise explanation. Done means a reader can tell what is being measured and whether higher or lower values are better.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
documentation
Issue type
Documentation
Difficulty
1/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.