How to best integrate Brain documentation

[goetzrobin]

Hey all! I am opening this discussion to gather your feedback on how we can improve the documentation, especially what you all think is a good way to add APIs provided by the brain primitives. Shadcn builds on top of RadixUI, which means that the shadcn docs can focus exclusively on the "own the code" and how Radix is applied under the hood.

With spartan/ui we are creating both shadcn & RadixUI at the same time! I want to think of ways how we can give developers better guidance to use the brain components themselves while also keeping the documentation clear, straightforward for all developers and maintainable for us!

Maybe some of you guys have seen great doc sites that they loved using or have examples we can try to emulate!

For reference here is the docs for RadixUI: https://www.radix-ui.com

I see they now have a themes section that adds styles to their primitives. Seems like they are keeping the docs completely separate. Curious to hear what you guys think!

Thanks already for your time & feedback!

Let's keep building together 👍

[thatsamsonkid]

Just thought I would help restart this discussion. I'm pretty interested and starting to document the brain component usage. Honestly I looked at a few component library docs. Just for reference:

https://spectrum.adobe.com/page/combo-box/
https://mui.com/base-ui/react-select/components-api/
https://ant.design/components/select#select-props
https://chakra-ui.com/docs/components/select/props

Honestly I think I really appreciate radix use of the table being condensed making it easier to see as many props as possible. With a few other libs I feel like they tried to put to much information in each row about each input/prop and it makes it difficult to read and makes me have to scroll. It feels like almost like information overload and makes the components feel complicated. I see this especially in the ant example. I think MUI tried to solve this by giving you the option to see the same information in a few different layouts but that might be a bit overkill.

Adobe's spectrum one is a bit interesting too. They have a pretty condensed table for quick reference of the inputs/props and they separately have a section for each one to give more info on the default and behavior. The use of the change log is of most interest to me from their example.

So in all I think:

• I think we can also just keep the api docs as another tab along with the "preview" and "code"
• We could have a similar condensed table of all the inputs/outputs for each Brn component/directive with type and default value
• Can keep descriptions in a tooltip or have them as a column in the table also but I think it would be important we kept it short and or we try to make the props as self explanatory as possible with their naming
• If we need to explain an input/output or behavior in more depth we can definitely keep a section of the page where we go through those similar to the adobe spectrum example
• I think it could be cool to show the changelog similar to how adobe did in the spectrum example.

[thatsamsonkid]

Just trying out some quick POC's I think we have 2 options although I originally thought we could just add another tab to the component intro. But unfortunately I think most of api references would be rather lengthy. So we could do it that way but we would probably want to limit the tab's height maybe so its not crazy long. So see option A for that.

Option A:

----

Option B: we can just have it on the page as a separate section and maybe just below the usage section. We can add subheadings so they are clickable on the right side pane as well

So the page flows from Install -> usage -> api -> examples

I think my vote is for B even tho it risks making some component pages very long I think since we have the navigation on the right should be ok.

Would love to hear what others think!

[goetzrobin]

My vote is also B! Looks great by the way! I think this will be awesome to add

[alexciesielski]

I like Option A in that it resembles Angular Material's docs (familiarity), and quickly allows jumping between sections.
Sometimes I open the material docs to check the examples and copy some code, but sometimes I just want to really quickly take a look at the API at some class or function signature.

[thatsamsonkid]

I really wanted it to be Option A but I think it doesn't work as well for us here because we have everything on one page and the tabs are only accounting for a small section of our pages instead of the entire page. Each tab in material site is a separate page. I think Option B might be the best way for us now. Although very interested in the idea @elite-benni brought up as well but maybe something we can look into a little later unless someone wants to volunteer into implementing that now.

[elite-benni]

I vote for B.
So you have everything on one page and can search for it on the page.
I am missing a place for additional information, like the little info icon on radix, should we also add something like this?
Sometimes an api Prop is not that self explained.

I had another approach in mind, since I am more a example guy.
My Idea was a page, or a section on the page, where you can change the values of the api and see result immediately.
Something like we have in Storybook, but for the props.

[goetzrobin]

Description seems like a good thing to have! I personally don't love the little ? icon on Radix and wouldn't mind just having a column called description. What do you think?

Interactive seems awesome, but also like a lot of work 🙈

[ajitzero]

+1 for ability to search on the same page

[thatsamsonkid]

I like your idea for having an interactive example! I think this could be very interesting but one thing I would mention that not all props would necessarily do or show anything immediately, so how do we handle that? Also if we have a primitive that has several parts to it some of the prop tables would be far from the "live window".

I think building on this it would also be really cool if we could render out the "current" code output for what they have in the interactive example but like @goetzrobin seems like alot of work 😅

I was planning to keep a longer description in a tooltip like radix does but im not opposed to having the description inline but definitely would advocate to keep them short! I'd prefer not have really tall rows haha

[elite-benni]

I have not thought a lot about it, but maybe we can come up with some "mini framework" that makes it easy to automate these things.
A dream would be, that I can plug in a component and all information is gathered automatically.
All public properties are listed and descriptions can be parsed from comments maybe.
Just thinking "loud". ;)

[thatsamsonkid]

Going to go ahead and create an issue for this and will take it on since I already started it a little bit if that's alright with everyone. I'll just go ahead do it for all components and we can refine any content for anything once I have an initial PR.