Qiskit / Qiskit/documentation

Deal with large and inaccessible Qiskit GIF

Open
#2,533 7 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

infra 🏗️
Dominant language
Jupyter Notebook
Stars
106
Forks
223
Avg merge
1d 8h
Merged PRs (30d)
72

Description

See https://github.com/Qiskit/documentation/blob/main/public/images/api/qiskit/depth.gif and its usage:

https://github.com/Qiskit/documentation/blob/be6687be304ffc3262c6c21bb6117d21531821f6/docs/api/qiskit/qiskit.circuit.QuantumCircuit.mdx?plain=1#L3490-L3500

Issues with GIFs:

  1. GIFs violate accessibility because of flashing automatically and not having a way to pause them
  2. The GIF is 2.7mb, which makes the page slower to download for users, even with the lazy loading Next.js uses. It also bloats our Git repository size in qiskit/documentation

Ideas for workarounds:

  1. Replace it with a link to our 1 minute video "What is circuit depth": https://www.youtube.com/watch?v=7AVIc7SkX3M
  2. Use text-based only explanation
  3. Remove it entirely

Migrating the file from GIF to AVIF only reduced the image from 2.7MB to 2.3MB, and it corrupted the GIF.

Note that this GIF is in our historical API docs. We should probably rewrite them to not have the image so that those pages load quicker & our repo size is smaller.

--

Response from Jake L in Slack, Dec 27

I tried to kill it once (for one, I disagree that it’s anything to do with tetris!), but there was some sentiment from within the qiskit-compiler team that it had helped with the understanding.

Fwiw, I feel like the entire “simple circuit metrics” section could do with a rework. It’s generally seemed to me to be targeted at a (now 6+ years ago) QC theorist who doesn’t know how to program, which probably was a core demographic at the time when Qiskit was in its infancy, but it’s not the best pedagogy now. (Fwiw, that section was mostly unaltered when the rest of the QuantumCircuit page was rewritten, because it was already good enough compared to the complete absence of everything else.)

That is to say, I’m strongly in favour of removing the GIF, and I feel like the description of “circuit depth” should have a text overview in the QuantumCircuit.depth and DAGCircuit.depth docstrings. If people think it merits a particular further explanation, the youtube link is fine to include for me, though equally that content to me is a bit more about the theory of QC and doesn’t necessarily belong in the API docs.

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

Read public/images/api/qiskit/depth.gif and the referenced QuantumCircuit.mdx section around lines 3490-3500. Review how the historical API documentation explains circuit depth and determine the agreed replacement for the GIF, such as text or the linked video. Done means the inaccessible, large GIF is no longer used and the resulting explanation remains understandable.

Written by the indexing model from the issue text.

Assessment

Tech stack
next.js
Domain
accessibility, content, documentation
Issue type
Documentation
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
38/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.