News for hackers. Stuff that matters.
Re:Slate, create beautiful, responsive API documentation by btown on Tuesday August 18, 2020 @01:45PM (#24201729)
As much as I love the idea of a single page, I've seen massive Slate docs where time-to-interactive is 10 seconds or more because even a modern browser on a modern machine struggles to layout such massive volume of docs.

See, for instance, Spreedly's documentation - an incredible service btw for future-proofing your payments stack and allowing PCI-compliant routing to practically any payment processor. (Not affiliated, just a happy customer!) The only time I'm not a happy customer, though, is when I'm time-constrained and have to load the docs, because this is their Lighthouse report:

https://lighthouse-dot-webdotdevsite.appspot.com//lh/html?ur...

> Performance score 8/100, first contentful paint 9.5s, TTI 16.1s, 5s for style & layout, 3.5s for rendering, 43k DOM elements

All that said, Slate is really great. I'm certainly not asking for Spreedly or anyone else to switch tech for their docs. The benefits outweigh the costs.

And I get that you can't have gradually-laid-out content and also preserve scroll position on refresh in a responsive environment. Theoretically, you could, but you'd need to exactly measure your text size at dozens of responsive breakpoints and pre-set each section's height, which would require a headless browser as part of the compile pipeline. And the last thing we want, especially this week, is advocating for documentation sites to take longer to compile. So perhaps this is the local optimum. But hopefully there are other more creative solutions!

Re:Slate, create beautiful, responsive API documentation by baddox on Tuesday August 18, 2020 @02:07PM (#24202053)
That is an absolute monster of a page, and while the JS is slow, that's not even where the problems begin. This thing is 1.5 MB of HTML, which takes 3-4 seconds just to download on my gigabit connection (it doesn't appear to support compression, which might help a lot).
Re:Slate, create beautiful, responsive API documentation by btown on Tuesday August 18, 2020 @02:27PM (#24202300)
Compression wouldn’t help the 8.5 seconds spent on layout and rendering of the text.