The 2,981 that overtook the 3,221 from the outside lane
Showing the misleading chart
A lightning-talk slide we drew races nine documentation tools round a running track, one lane each, with the angle of every lane’s bar set by how many Stack Overflow questions carry that tool’s tag. The axis is linear and starts at zero, and every count is printed. But the lanes were handed out alphabetically, and a bar bent into a circle is a length multiplied by its radius. Javadoc, with 2,981 questions in lane 3, is drawn 1.23 times longer than Doxygen, with 3,221 in lane 2; Sandcastle’s 305 is drawn 1.67 times MkDocs’s 304. A real track staggers the start so every lane runs the same distance. This one doesn’t, so the outside lanes run further.
01The claim
Nine documentation tools, nine lanes, one race: how many questions developers have asked about each one on Stack Overflow. The counts come straight from the Stack Exchange API, one per tag, unsmoothed and unrescaled. The angular axis is linear and zero-based, 0 to 4,000 questions over 270°, so 100 questions is 6.75° in every lane. It is gridded every 500, and every count is printed at the end of its bar. Sphinx is out in front, Javadoc has come round the outside to take second from Doxygen, and Docusaurus, a modern static-site generator built for docs, has barely left the blocks, beaten even by Sandcastle and MkDocs.
02The trick
Every count on the slide is right and the angles are honest, but the reader is not measuring angles. A radial bar chart bends each bar into an arc on its own ring, and an arc’s length is its radius times its angle. The angle is the data. The radius is the lane, and the lanes were handed out alphabetically, so docusaurus got the rail and sandcastle the outside. Every bar has been multiplied by a number that came from the spelling of its name. Running tracks deal with this by staggering the start: the outside runners start further round so that everyone covers 400 metres. The chart gives every lane the same start line at twelve o’clock, so the outside lanes simply cover more ground. Lane 2 has a radius of 78 and lane 3 of 104. Doxygen’s 3,221 questions sweep 217° in lane 2, an arc 296 units long. Javadoc’s 2,981 sweep 201° in lane 3, an arc 365 units long. That is 1.23 times the ink for 240 fewer questions: (104 ÷ 78) × (2,981 ÷ 3,221) = 1.33 × 0.93 = 1.23. The lane outweighed the data. At the bottom of the table it is starker. Sandcastle (305, lane 9, radius 260) and MkDocs (304, lane 5, radius 156) are one question apart, and Sandcastle’s arc is 1.67 times as long, 260 ÷ 156. Docusaurus has 515 questions, more than either, and draws the shortest arc on the track, 32 units, because lane 1 has a radius of 52: Sandcastle gets 2.96 times the ink with 59% of the questions. Across the chart a degree on the outside lane draws five times the length of a degree on the inside, 260 ÷ 52, and that multiplier is printed nowhere. Ranked by drawn length, five of the nine tools are out of place. None of this is a verdict on the tools; the short bars are an accident of the alphabet.
03The fix
Lay the nine bars out straight. The redraw puts the same counts on one zero-based horizontal axis, sorted largest to smallest, each bar starting at the same baseline: python-sphinx 3,831, doxygen 3,221, javadoc 2,981, jsdoc 1,780, phpdoc 911, roxygen2 668, docusaurus 515, sandcastle 305, mkdocs 304. Doxygen is back in second, Docusaurus climbs from last to seventh, and Sandcastle and MkDocs come out the same length. Each tool’s old lane is printed faintly beside its bar, so you can see that every promotion went to an outside lane and every demotion to an inside one. Why not just stagger the track? You could shrink each angle by its radius so that every arc’s length is proportional to its count, but then the angles no longer mean anything and the gridlines are useless; a straight bar gets the same result more simply. Sorting the lanes by value fixes the order but not the ratios, because the biggest counts would still be multiplied by the biggest radii. Keep the circle for quantities that really go round, like hours of the day or wind directions. The straight chart also leaves room for what a tag count does and does not measure. It counts questions that carry the tag today: deleted ones are missing, and a question tagged both doxygen and javadoc counts under both, so the nine counts are not 14,516 separate questions. And it is not a difficulty score. A count grows with a tool’s age, the size of its community and whether its users ask on Stack Overflow or elsewhere, and the site gets far fewer new questions than it did a decade ago.