Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Make component model docs more accessible #101

Open
divya-mohan0209 opened this issue Mar 7, 2024 · 1 comment
Open

Make component model docs more accessible #101

divya-mohan0209 opened this issue Mar 7, 2024 · 1 comment

Comments

@divya-mohan0209
Copy link
Contributor

One consistent feedback I've received for the Component Model docs is that our docs are too complex for an average reader to consume. This does mean a LOT of things, but as a starting point, these are the things that I can think of:

  • A style guide: This will help people who want to contribute to the docs understand the language and notations they must use. It would also be helpful for reviewers and approvers to have this guide as a reference. We can use some, if not all, of the recommendations from the Kubernetes Style Guide. Of course, this would also require us to maintain and iterate over it in the long run.
  • A contributor guide: Again, I will shamelessly borrow an example from the Kubernetes documentation. We need this to signpost future contributors to our documentation efforts and have them understand how to contribute specifically to the docs.
  • Incorporate a working search bar in the docs: This will help people quickly navigate to the keyword or concept they're searching for and see if there's anything related to the topic.
    Google Analytics integration: This is kind of self-explanatory, but searching the Wasm component model/WebAssembly component model/component model in a private/incognito window doesn't bring up our docs website in the first three or four results. By integrating the GA4 plugin, we can understand user behaviour and analyse how effective our documentation is. After that, changes can be made based on the findings, and we can redesign our SEO.
  • SEO strategy: This point ties into the previous one because searchability is a massive factor in newer folks discovering our docs. So, we must dedicate significant time to thinking about how we get into the first couple of results on Google search.
  • More graphics/images: Images and graphics drive our point home and help with retention. We should consider reinforcing concepts graphically with ALT text + captions. We must consider the graphic/imaging software we intend to use with our current SSG since not all frameworks integrate well with every SSG.

I wanted to set the ball rolling on discussing some of these & bring it up as something we can hack on further at Cloud Native Wasm Day since some of us are likely to attend it in a few weeks.

@vados-cosmonic
Copy link
Contributor

Hey @divya-mohan0209 do you feel like these issues have been addressed? The component model docs have evolved a lot, and there is a contribution guide that makes things a bunch easier.

One big issue that I think isn't addressed is having more graphics/images, which I'm happy to make a specific follow up issue for (and maybe help with implementing!)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants