Open whoisryosuke opened 4 years ago
I think Gatsby would be a nice replacement for the current docs, but only if it consolidated all the content of the Storybook, the Docs and all the CodeSandbox snippets.
If Grommet moved docs to Gatsby with the same content and continued to fragment all the information between three websites, there would be zero net gain in moving to Gatsby IMO.
So generally I'm in favor of this proposal, but let's also think about how to reduce the tribal knowledge in Grommet and improve the information architecture of the docs.
@karatechops for review
@whoisryosuke, thank you for the detailed discussion points. I've recently merged a PR which adds an extra build step to create a static build, resolving a few overdue SEO issues. Our goal for the Grommet site is to keep it low touch and simple. In the spirit of Grommet, we try to build custom for our use cases and not rely on heavy libraries.
I do believe we need to better streamline avenues of documentation for Grommet as @iMerica mentioned. However, I'm not certain that the argument regarding anyone can edit MDX is valid when the author would generally need to already be consuming the library to be creating documentation for it.
Maybe @L0ZZI can chime in regarding the use of a sidebar. I presume it goes back to the "keeping things simple" mantra. Additionally, one of the patterns we're leaning into with Grommet applications is search-based navigation rather than lengthy nav lists.
I can certainly understand the benefit of a Gatsby Grommet docs site but I'd want to see the team re-think how all of the information is presented first then we would choose the framework that is best suited to the design and concept rather than engineer first.
@iMerica I like the idea of consolidating the content and using Storybook as the basis for examples, especially if CSF format is used. Should be able to just import them into the MDX file, or build a script to loop through it (to append after the MDX content).
If Grommet moved docs to Gatsby with the same content and continued to fragment all the information between three websites, there would be zero net gain in moving to Gatsby IMO.
Not sure what you mean by this? Where does the third site come from?
The point of Gatsby is to be a complete abstraction on top of the Grommet source code, which would become the source of truth, containing all the documentation content (prop types, theme props, custom written Markdown, etc). If Grommet decided to switch off Gatsby in the future, you'd develop a new site and (ideally) import docs data from the Grommet source code. No content should be migrated from the docs. MDX files should be collocated with the Grommet source code, not the docs site.
Gatsby would reduce the overhead of the current documentation site by reducing the number of files immensely. Rather than manually defining everything, Gatsby has ways for handlings things like generating routes. It's much easier to tweak a configuration file than manually edit n * component
files (and the route file, and any manual navigational references, etc...)
@karatechops appreciate your thoughtful response! It's nice to hear that there are movements towards optimizing the current documentation build process (as well as SEO). Is there a branch we can check out? 👀
Simplicity is fantastic until it hinders productivity. For example, the react-desc
library like I mentioned earlier, holds the entire documentation back because of it's custom implementation. If a more standardized approach had been used, like JSDocs, the source code would have been more easily integrated and parsed by common documentation solutions (like react-docgen or Docz). This would make the code base more future-proof, as opposed to siloed.
Same with the build process. Why spend time and development effort optimizing a Webpack build for the old docs (that isn't really doing anything crazy custom anyway), when there's a framework that offers a much better configuration and results for possibly smaller effort?
I'm all for creating custom solutions to create smaller libraries, but when it comes to devops (and dev dependencies), many of these "heavy" libraries are only used during build (usually as CLI) and never seen on the client slide. Gatsby has a footprint client-side, but I think it's clear from the performance report that it's clearly not an issue 😊 And with tree shaking, if the libraries that are used are optimized, there shouldn't be a major concern for excess code on the client-side.
The point of MDX is that it's a much easier authoring experience than writing a very strict JSX file. The developers can totally be capable of accomplishing it, but it's about reducing the friction and time it takes to create and edit the content. If I'm writing, I want to write, not write and code.
For example, how would someone add code examples to the current setup? (Presuming we change the way that the <Doc>
component works...) It'd have to be a string literal with code example inside, and then used in the <Code code={code}>
component (somewhere on the page). If I have multiple examples I have to create many different variables, manage the names, and when I need to edit them scroll up away from the text (to outside the render scope). MDX would allow writing code examples inline.
I'm cool with the search based navigation vs a sidebar if minimalism is that key -- it just needs a more solid UX if it's the only lifeline across the application. A keyboard shortcut would be great to quickly pop back up to the search and find the component I need. Often when searching through docs, the common way to bounce around between components is using the Find hotkey (CTRL/CMD + F), and typing the component name and finding it in the sidebar. This wouldn't be much different from a dedicated keyboard shortcut (like hitting the /
key) and scrolling me to the opened search input. The only issue with this method is educating power users, and finding the proper place in the docs for it.
Totally agree that the team should revisit the content and structure of the documentation before moving forward a migration. Things like official Theming docs are critical before build performance. But I think Gatsby should be heavily considered as a solution when discussing the next docs iteration, mostly because it would help standardize the codebase in a more future-proof fashion.
Recently I've been on the hunt for React UI libraries that handle theming in an easy and extensible way. After a bit of comparison, Grommet ended up utilizing one of the most ideal architectures for styling and theming components. Grommet uses Styled Components (instead of object-based syntax like JSS), it handles theming properly (design tokens + minimal component tokens/styles), and it has many of the base components you need (from buttons to inputs).
I wanted to use Grommet as a basis for a design system and contribute to the library. However, the documentation for Grommet is a bit lacking. And after looking into the source code, I wasn't happy with the way the code was actually documented. So I set out to create a more robust documentation website that was more inclusive for contributions, included more content, and faster overall.
Not sure if this should be in the main grommet repo or not. I can re-file this there if necessary.
Problems with docs (and solutions)
grommet-site
repo), but they aren't actually used in frontend anywhere.gatsby-node
, which can generate pages/routes from content it imports into GraphQL.react-desc
, a custom integration for Prop Types. This made the documentation of props inaccessible unless you created an adapter or custom import for the special syntax.docs.js
file there. Or if I want to I need to edit the corresponding file in thegrommet-site
repo. Ideally I should be able to keep all docs together, or pull from a single source. Whether it's JSDoc blocks, PropTypes, or MDX — there should be less context switching when composing docs. The documentation site should just pull all the data from the source code, and only contain logic for the docs themselves (layout, doc-specific components like code blocks, etc).Ideal setup
PropTypes descriptions are pulled from comment blocks.
Examples and any extra documentation copy are written in MDX files.
Design tokens, utilities, etc are separate from component definitions. Right now the main site navigation is just a list of components + design tokens (color, spacing, etc). It makes it seem like Color is a component, when it's just a doc page for defining the design tokens.
/src/js/components/
folder for any MDX files. Since there is no<Color>
component, a "component-style" page won't be created for it, and it won't be grouped similarly in listings. Instead, a new MDX "page" is created inside the docsdocs/src/pages/
that contains the color token documentation.It's honestly not too different from the current setup. There's just more examples, more documentation (on theming, general use, architecture and semantics), and less code — all sitting on a better stack that enables better UX on the frontend and contribution side.
How to accomplish
react-desc
and replace with JSDocs.react-docgen
(the new docs parsing libary) doesn't pick up separate files with PropType definitions. Need to combine them back into the main file. Move props fromdoc.js
to component file, underneath component.doc.js
andreact-desc
format into JSDoc blocks with classic prop types.Other problems
After a bit of initial exploration and experimentation using Gatsby and Docz (a docs template based on Gatsby), I started to notice some other strange issues with the code base.
MDX getting picked up from random source files.
MD is malformed
Test keep failing?
Couldn't commit to repo because 100+ snapshot tests would fail. Not sure what I was doing wrong here, could totally be on my end. Didn't change anything in repo except moving prop types in the Button component, and apparently broke several other component's snapshots.
Had to make commits with the
--no-verify
flag enabled.Linting issues.
export Button from "./Button"
vs import then export), despite them being enabled in the repo's config? Could be my own linting config in VSCode overriding the default config?Not an issue, but tried using typedoc to generate JSON for component props (rather than JSDocs with prop types). You could use the JSON generated by typedoc in Gatsby to render prop table for component.
Unresolved Features
doc.js
file as an exported variable in object format. These not only contain component-specific theming values, but what global theme values apply to the component. This helps immensely when theming.doc.js
totheme-docs.json
. Only contains theme values, no more prop types since they're collocated with component code. Import the JSON into Gatsby using the JSON transformer plugin. Then on component pages, query the JSON via GraphQL, and display in a table format.The Result
After a day of tinkering or so, I whipped up this proof of concept using Gatsby, MDX, React-Docgen to generate documentation based off a slightly modified Grommet library. I converted one Grommet component (
<Button>
) from usingreact-desc
to JSDocs. The rest happens all inside Gatsby.It doesn't feature all the component pages, or new content (like theming docs). Those are a bit more time consuming or ideally community driven / discussed. However I thought this prototype would illustrate the architecture changes I'm proposing.
gatsby build docs
When you run Gatsby's build process, it's "source" plugins check the Grommet
/src/js/
directory for any React components and MDX files. Then Gatsby runs any "transformer" plugins which read any imported data (JS and MDX) and parse it into GraphQL nodes and endpoints. Pages are then created - some are static, while others get created dynamically ingatsby-node.js
using GraphQL queries. Most pages are dynamic, like components and MDX content, which get run through page templates in/docs/src/templates/
. These page templates use GraphQL to query for their data, and pass it down to the appropriate components.The final product is static PWA that offers features like page preloading, offline support, and image optimizations. I also added live coding support to more examples. This way users don't have to load a new CodeSandbox for each experiment they want to test (which can be intensive + unnecessary if you've already saved the docs offline).
Deploying the documentation in production would also require production deployment of the UI library's source code documentation (since the Gatsby docs uses Grommet as NPM dependency, and pulls production content from there). This is why the live demo is deployed on Netlify using a static build process that's manually uploaded, instead of deployed via git commit.
Comparing Performance
Let's compare these Gatsby docs to the current iteration of the Grommet v2 documentation. These metrics were created by Lighthouse running on a MacBook Pro, set to Mobile and Simulated 4G with a 4x CPU slow down. I'm pretty sure both sites are hosted on Netlify, making it a great baseline CDN.
Page load
Grommet v2 docs:
Gatsby Prototype Docs:
What do you think?
Thank you for your time and consideration! Please feel free to ask me any questions 👍