style-dictionary
style-dictionary copied to clipboard
amzn
[RFC] New Documentation Site
✨ Request For Comments ✨
Pretty soon we are going to migrate the doc site off Docsify into a separate package using something like Gatsby. Nothing against Docsify, it is great for what it does, but we have outgrown it. There are a few reasons for this:
- More stability: we have had some issues with the doc site on Docsify, some our fault, some Docsify's. We have an active issue about 404's on our doc site because of these issues.
- Better SEO: moving to a SSG (static site generator, like Gatsby) will provide better SEO and a faster experience
- More flexibility: building a legit doc site we can do a lot more with the features of the site.
- Mostly, we have outgrown Docsify. It is great to get a simple doc site up and running on Github using markdown files, but I think it is time to build a grown-up site.
I want to take this as an opportunity to get feedback from the community to see what you would find helpful in a new doc site. Things you would like to see, things that you would change from our current site, things that you like with the current site that we should keep, etc. All comments and suggestions are appreciated. If you have any thoughts on the technology of the site, like Gatsby or 11ty, separate package or monorepo with Lerna, let us know that stuff too.
Also, if anyone would like to help build the doc site let us know.
This just made its way in my GitHub activity/timeline: https://github.com/johno/gatsby-theme-documentation
Right on time :)
I have a few questions, just to start the discussion:
- I imagine that with "documentation" you mean the whole website (this: https://amzn.github.io/style-dictionary/), right? in that sense, is more than a documentation site, is also a "promotional" site (in the sense that it showcase the "selling points" of StyleDictionary (especially now that "design tokens are so hot"); this also means that we should not forget the "visual design" of the website/documentation
- which leads to my second point: should we collect a few links of which website we consider good examples of a website for an open-source project, to use as reference/guide? thinking of http://styled-components.com or https://nextjs.org
- are the /examples part of the documentation? what I mean is, how we "integrate" the documentation with the examples, to make them more useful (and discoverable?)
100%. Definitely more than just documentation, it should be a promotional/marketing site as well. I do want the visual design to look amazing as well as useful to all types of users (new to design tokens, new to style dictionary, looking for specific API documentation, etc.). This is why we want to get the community involved in the design of the website; all the code will be open source and easy to contribute to of course. The examples are definitely part of the documentation, I do want to integrate the examples so they are more discoverable. That does remind me that I wanted to also potentially have a "showcase" of open source codebases/examples using Style Dictionary as well. And of course open to whatever ideas people might have!
I like both of the examples you gave. I like NextJS's learn section, I think it might be good to have something like this that can be read sequentially. The ones I've been eyeing:
- Gatsby: I like their IA, especially having tutorials and recipes along with a showcase.
- NuxtJS: I like the simple design (minus the sponsors section taking up a lot of the secondary nav), and the simple top-level nav: guide, api, examples, faq, ecosystem
No comments from me on the technology.
Core pieces:
- Promo stuff (pretty, use cases, video, easy links to the stuff below)
- Style Dictionary playground (try it before you buy it)
- Dedicated Examples documentation (first party)
- Gallery of Third party examples
- Getting started / walkthroughs
- Full API Reference
The key difference I would like to see from our current site is better sectioning of content and better linking between them. (eg. the API is very separate from the Examples is very separate from the Getting Started)
Would love help with the redesign! Still in the early phase right now, so any inspiration or awesome doc sites would be great to have on this issue.
@chazzmoney love all those ideas, especially the playground. It would be cool to have the doc site styles built with Style Dictionary, and have an editor that will update the styles of the site...
Some fun sites that are in the same arena:
Some of these are just lovely to look at, others have amazing content. Mapbox, for example, has stellar documentation. If I'm logged in, I can go to their documentation site and get working code (with my info) and get my app working with little or no history or expertise, that's pretty amazing.
But while none are perfect, they all have something I like.
Found a couple more good-looking sites for inspiration:
- http://www.passportjs.org/
- https://ant.design/
Both mainly for their visual design and touches of animation. Pretty well crafted.
Another thing I want to fix with the new documentation site is make it easier for people to contribute to the docs. We have gotten lots of PRs where people make a change to a markdown file that is being generated. It is confusing to people that we generate markdown files from JSDoc comments, so I want to fix that.
Another suggestion that came up is to have more guidance on token organization, thinking about different types of tokens, and when to NOT use tokens.
I would suggest that you use VitePress. It has out-of-the-box support for SSG and is quite often used for documentation.
