Generated component docs
dabbott opened this issue · comments
I'm starting this thread to list out some misc ideas I've had around component docs. I think I'm personally going to be more focused on improving the core Lona studio/compiler functionality than docs for now, so this is more just to get the conversation started.
Thoughts in no particular order:
- When we build the docs site, we should try to use Lona for the colors and type scale. One of the coolest parts of this will be that people can totally customize the look of their docs site just by tweaking the docs' Lona workspace and regenerating it.
- If we end up thinking Lona will be useful for creating some docs components, that's great, though if we don't think it'll save time that's fine too. We're already building plenty of Lona with Lona, so no need to do it unless it seems like a time-saver.
- The docs site & workspace could easily be a separate repo, but so far the monorepo thing has been working well.
- For design direction/inspiration, I'm a big fan of the Apple docs, e.g. https://developer.apple.com/documentation/scenekit/scnscene. I find them easy to navigate, very clear language and lots of pictures, easy to switch programming language (swift/obj-c), discover related APIs, etc.
- mdx is pretty cool. It's pretty easy to build interactive docs with embedded components and playgrounds. I could see this as a good way to let people build rich docs that incorporate their tokens and components in interesting ways. The only downside is that markdown is relatively unstructured -- so it's a solution to rendering individual pages, but we'll likely need to store/determine site structure in other ways
- In order to display components in the generated docs, we'll want to use the exact same logic that the compiler uses, to prevent rendering inconsistencies. This could either mean directly invoking the compiler and generating JS code, or it could mean separating out some of the compiler logic into a separate shared dependency. Probably we want to go through the compiler directly, since that'll be less work.
- If we render docs pages within Lona Studio, we should probably start with it as a webview so the UI will look exactly the same as the generated site. This might mean we need a better caching strategy around generating docs, since we won't want to wait ~10+ seconds for compiling the entire workspace before we show docs.
- I do think a native markdown + component renderer in LS would be cool too though. It'd probably be able to integrate more tightly (e.g. clicking things in the docs and showing the Lona inspector... though I'm sure we could do this with a webview version too), and we probably wouldn't run into the same perf issues.
- If you haven't seen this project by @GuillaumeSalles, definitely check it out: https://github.com/Lona-Web/Lona-Web. This is a prototype of a docs site rendered from a Lona workspace.
For design direction/inspiration
My go-to example of a nice DS documentation is https://polaris.shopify.com (component page example).
The only downside is that markdown is relatively unstructured -- so it's a solution to rendering individual pages, but we'll likely need to store/determine site structure in other ways
I think each component should have an mdx field (description). You can also create mdx files in your workspace to create pages for high-level documentation. The structure of the workspace can then be translated into the structure of the documentation website: README.md -> index.html, etc..
I played a bit with gatsby a while back and was able to generate a documentation website from a design system repo (that used react-primitives components). You can create a "source plugin" that will look for and understand a .component file and translate it into a react component. The translation can use mdx and the lona compiler to generate it. It can also understand mdx files the same way.
people can totally customize the look of their docs site just by tweaking the docs' Lona workspace
Where would that workspace live tho? Would it be a nested workspace in their own workspace that gets added the first time they generate the documentation website? Wouldn't that create a lot of noise in their repo? (I don't have a good solution)
https://www.docz.site also comes to mind
I think polaris does some things well, like content guidelines. I find the overall UI kind of awkward to navigate. The navigation and margins are so big that it doesn't leave much room for content. It would be nice if the code sample were editable. It's also awkward that the props editing form is below the code sample, since I have to scroll up and down to actually see my changes. And iOS/Android show much less info than web (e.g. no props/types). But I'm sure there are a lot of ideas we can borrow from things they do well.
I think each component should have an mdx field (description). You can also create mdx files in your workspace to create pages for high-level documentation. The structure of the workspace can then be translated into the structure of the documentation website: README.md -> index.html
That sounds good. I can still imagine wanting other structure: e.g. how do you order the custom mdx pages within a workspace when listing them out on the docs site? But we can try it out and see what happens. The old docs editor stored the markdown in metadata.description (now it's just that weird tiny field in the Details tab)
Gatsby seems like a solid option. It would allow a lot of configurability beyond just Lona-related stuff, and people could easily integrate Lona component docs into existing sites.
I love gatsby conceptually... but find that in practice it's pretty buggy and hard to debug plugins. I'm a little wary of adding such a fragile dependency. But maybe that's just my experience.
Thinking out loud... if it's totally separate from LS then I wouldn't be as worried. To display mdx docs in LS we could either run a gatsby server or have a separate code path -- if we have a separate code path that doesn't rely on an external process I could imagine it being a bit more stable (it could still run the gatsby code, just differently).
Where would that workspace live tho
A nested workspace is an option. I've been imagining docs site v1 is a totally separate workspace that we make, but that people can fork and tweak if they want. I.e. if people use the default template they don't see any of the files in their repo. I guess that would lend itself to being separate from this monorepo for easy forkage. Maybe there's a better way, I haven't though too much on this
I tried this when it first came out. It was pretty primitive/underwhelming, but I'm sure it's better now and worth looking at again