Documentation website

[vgeorge]

Context

Currently, this component library doesn't have a dedicated documentation website, relying on Markdown files referenced in the README.

I believe a public documentation website would make it easier for users to find guides, APIs, and examples. At the same time, we should aim to minimize additional effort in maintaining documentation.

I looked into documentation.js and Storybook and suggest using the latter for this project:

• Offers a sandboxed environment to demo and test components in isolation
• Generates documentation from JSDoc comments automatically
• Integrates with Playwright
• Already used in Devseed UI, leveraging existing team knowledge

Looking forward to hearing thoughts from the team.

Related Tickets

• Test Coverage for Existing Core Features #1200
• Ensuring a Clean, Reliable, and Developer-Friendly Codebase #1263
• Integrate Playwright tests in the veda-ui #1197
• Start NextJs Instance Documentation #1368

[hanbyul-here]

👋 Thanks for your thought. This would be def step-up from what we have now.

I can't think of any objection to take more automated approach, and it would help us to keep the documentation in comment more up to date. Also more component based documentation will be necessary as we move veda-ui to registry. There are some elements that I hope to get more a more specific picture.

There are many non components specific documents sprinkled all over VEDA. (Two examples : https://github.com/NASA-IMPACT/veda-docs, https://github.com/NASA-IMPACT/veda-ui/tree/main/docs) - Is this documentation will be the central point of VEDA UI?

Storybook does offer really nice automated features, but as far as I am aware, we still need to put some efforts to make the example work etc. (Please correct me if I am wrong) And I am a concerned about diverging our work even into more items when we already have lots on our plates. Can you give us a rough estimation on the creation/maintenance of Storybook?

[vgeorge]

@hanbyul-here thanks for the feedback. Regarding the different documentation sources, it might be helpful to focus on enhancing the existing documentation in this repository, surfacing the markdown files you pointed to and, at a minimum, adding the components' API. I don't think we need the examples if they are too involved to implement.

The veda-docs repository appears to have a broader scope, and it could be beneficial to keep it separate while referencing relevant documentation from this repository as needed.

As for the effort required to implement Storybook, I don't have an estimate at the moment. Given other priorities, we can consider whether it's the right time to move forward with it. If there's interest in exploring it further, we can reach out to the team members who implemented it in the DevSeed UI Library to gather more insights and provide an estimate.

[j08lue]

VEDA UI's sister project eodash has this: https://eodash.org/

EOX is also using Storybook for their EOxElements https://eox-a.github.io/EOxElements - only used internally so far

Just FYI