You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
The text was updated successfully, but these errors were encountered:
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!)
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:
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.
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.
The text was updated successfully, but these errors were encountered: