rusackas commented on issue #32625: URL: https://github.com/apache/superset/issues/32625#issuecomment-2773752431
Happy to dive deeper here... the "Developer" role is one of the archetypes that'll be served by the proposed information architecture revamp: - **User Docs**: Perhaps self-explanatory, but the User is anyone that needs "how to use Superset" tutorials, and this is where they'd go... whether that's building charts/dashboards, using any other user-facing features. - **Admin Docs**: This would be the more non-user-facing stuff for those who install/maintain an instance. Installation instructions, configuration, upgrading, feature flags, database installation, scaling/troubleshooting info, etc. - **Developer Docs**: The Developer role would be anyone adding to or expanding Superset, or building with Superset parts. This will be where we put what I was initially considering as the "new" developer portal. Primarily SDK docs around the tooling and interfaces for Extensions (in service of [SIP-151](https://github.com/apache/superset/issues/31932)). This could/would also include documentation around Superset components (essentially like Storybook, but possibly with Codepen-like interactivity as well). This may also include API docs, whether theat's today's Swagger page, or a revised version thereof (Redocusaurus, Stoplight, etc). - **Contributor Docs**: This would be all the info on how to work with the repo and codebase, in terms of "how to" info on PRs/CI/pre-commit/etc., as well as "best practices" pulled in from the current Wiki, contributing to maps, and any other rules/info/tools that might be pertinent. - **Community Docs**: All the resources, community guidelines, affiliate/partner info, content resources, calendar, etc. that would help people find and engage with the project on a community level. - **Packages Docs**: This will provide resources around the bits of the monorepo packages and Extensions provided with Superset. The UI components would be equally at-home here as they are in the Developer Docs, perhaps. This is all based on packaged/versioned assets, so the Docusaurus multi-instance versioning schemes will be critical here. As for the automated documentation, this part is admittedly a bit ambitious, but I'm looking at `Typedoc`, `jsdoc-to-markdown` or `documentation.js` as some options where markdown files can be auto-generated for code with properly formatted JsDoc comments. I don't imagine there'd be any need to do this for the entirety of the codebase, but it could be quite handy commonly used things like utilities from `@superset-ui/core` or for bits and pieces of the Extensions project, when we want to document/demonstrate methods/utils/interfaces. For Python code, I'm imagining certain utils (like post transformation utilities used by viz developers) may benefit from things like `pydoc-markdown` or `Sphynx`+`MyST`. This is stuff that needs a bit more POC work, but I imagine it'll be a "leverage where needed" situation more than trying to go through and document the whole codebase. Similar story for the AI documentation generation, for anyone wondering. We're using several AI tools on the repo, and there are several more to explore. The goal here is not to let the robot run wild building pages, but rather to gain insights from Slack/Website/GitHub questions and issues, and come up with new docs content to fill gaps... but I fully expect this will all require human editorial oversight, since we certainly don't want a docs site full of hallucinations 😅 -- This is an automated message from the Apache Git Service. To respond to the message, please log on to GitHub and use the URL above to go to the specific comment. To unsubscribe, e-mail: [email protected] For queries about this service, please contact Infrastructure at: [email protected] --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
