▲ 121 points
back
25 comments
I like the way it looks, and the fact it more or less works even without javascript enabled is nice bonus, many other similar documentation solutions can't do that. I'm torn about whole documentation being in one page, it certainly makes it easier to Ctrl+F, but it's also easier to get lost.
But it has still some bugs to work on. I tried opening Travis CI documentation to see it in action. When reaching [0], I wanted to scroll back up. Using Firefox 79, I wasn't able to go up no matter what. When using Chromium 84, I managed to go up when scrolling fast, but when holding up key, I still stayed in place.
I reviewed Slate for one of my clients' private APIs. We ended up using Postman's API docs instead. The logic that brought us to that point were:
1. The ability to generate/sync documentation from a Postman collection meant we could write our test suite and documentation in one step.
2. Since we were already paying for a team account, adding Postman documentation was practically free.
3. Environment variables. We could write our test suite with one set internally and then publish our API docs with another set.
As someone else pointed out, it's possible to generate Slate documentation from an OpenAPI spec, but to me Slate on its own leaves a lot to be desired.
I just recently went with Postman's API docs for these same reasons. Having used Postman to test while building out my API, it was refreshingly easy to take the extra steps of doing everything "properly" – fleshing out the rest of the variables by pulling out any static values, creating extra descriptions in Markdown, etc – in order to publish it as living documentation.
Correct me if I'm wrong but if you use swagger / open API you can abstract out your docs and they're portable?
For the project I'm talking about there wasn't an existing swagger implementation. The bottom line ended up being that since we had tests in Postman anyway, generating documentation became a few small steps (Add nicer descriptions for folks outside the org to consume, then click a button basically).
Can elaborate what you need exactly and what Slate does not offer?
Honestly, like all decisions, there were many factors. A big hurdle in this instance was that the existing application was written using a PHP framework that made generating something like a SwaggerDoc an extreme pain. Since we knew we'd have to write documentation outside the product anyway, and we were already using Postman for tests, using their (free, and already hosted someplace) docs was a no-brainer. It even allowed us to share the docs with 3rd party developers in a way where they could import the docs locally and run them -- again, via Postman in order to test their own uses of our API (simply by setting up a few variables like putting in their API key).
From point 1 it sounds like they already use Postman for testing and so using it for documentation makes it easier - perhaps its somewhat automated.
I've used this before (as an API consumer, not an author), and while it's better than many other documentation sites, for some reason the "scrolling will change the URL and active navigation item" was really disorienting. I kept finding myself lost in the one long stream of documentation -- there was no anchor!
The goal is to have everything browser-searchable (i.e. ctrl-f), and I think it's a good goal. I wonder if there's a better way than having everything on a single page with very little compartmentalization, though.
Since it's a static site, splitting the content across multiple pages and still being searchable would mean you'd need to push the whole search index down to the client and have the search operate locally. Not that it couldn't be done, and I can think of a few optimizations, but for the "very large docs" use case that's called out in the readme, it might still amount to a lot of data on top of the "a lot of data" that constitutes the docs themselves as rendered. Relying on browsers' built-in text search makes a lot of sense, especially to start with; I'd likewise wait to see a very strong use case before building out my own search to supersede it.
I don't know how I feel about the way they're managing the URL fragment. The way they're calling pushState, it adds history entries while scrolling, and that makes the back button behave nonintuitively; I think I'd rather see history entries created only when I click a header, or otherwise take some specific action to demonstrate the intent. That makes the back behavior easier to reason about, and also preserves the easy deep linkability that they are, imo rightly, going for.
If you load all the content from the start, you also push the entire index to the client.
It could even be faster because all the HTML markup can be left out for the search index.
If you do it as separate static pages, though (per the upstream comment: "I wonder if there's a better way than having everything on a single page with very little compartmentalization...") then you're no longer pushing all the content to the client at once. That limits the scope of the browser's built-in search to the current page, and thus necessitates the additional complexity to regain support for searching over all the docs.
Thanks for posting that. What I like about slate is that it seems to be searchable via Ctrl+F which makes it an advantage over ReDoc where search is broken IMO.
We are currently reviewing several API doc creators including commercial once. And none of them seems to have the feature that I can perma link to a certain request (or response) parameter. E.g. /api1#some/nested/parameter. This seems to me very useful as we don't have to copy the description and type of the parameter again.
You see what I mean when you go to the slate example page https://slatedocs.github.io/slate and search e.g. "available" then you click on the result and you will be directed to the "Get All Kittens" instead of the parameter directly which is confusing if you have more than a few parameters and you have to scroll down. I.e. Ctrl+F is better than this Search feature.
The same problem exists for ReDoc. We tried to contribute a change that supports this perma link feature, but it was not even reviewed.
Any recommendations?
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!
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).
Compression wouldn’t help the 8.5 seconds spent on layout and rendering of the text.
I've seen Slate. I know CircleCI uses them. Personally however I am a huge fan of redoc. Something about the way redoc looks and the way it is served makes me want to pick them over slate.
https://github.com/Redocly/redoc
I've managed to get both the companies I work at use redoc instead of slate :)
Can this be generated from an OpenAPI3 spec?
This seems to be the most supported project to convert OpenAPIv3 + other docs specs to a Slate compatible format.
I’ve used this with the CLI wrapped version that’s linked to in the readme and it works well enough. There are shins bugs/gaps in the template where some OpenApi fields are not rendered though.
In the end I containerized the whole thing with defaults, logos, etc so we’d have standard docs with little effort.
While I like how it feels and look, I really miss being able to have a try button. Like on swagger, I want to add test data and try it.
This is one of my favourite features when I explore APIs of other companies.
I'd love to be able to generate Slate docs for a GraphQL API from an introspection query.
Me too. Having used Altair/GraphQL Playground/GraphiQL, there is a lot that can be done in the automatic doc generation/ interactive query space. E.g. it would be very useful to see a schema/ER diagram like visual representation driven by introspection.
is there anything like this but in pure javascript/typescript ?
ideally a SSG like Gatsbyjs or Nextjs
Something like https://github.com/facebook/docusaurus