Updated accessibility docs #109
Conversation
There was a problem hiding this comment.
Thanks, @mlama007, this is a great write-up!
However, I have a major concern: this guide here is very general and not Vue-specific. The main part touching Vue is about vue-router and Vue Router doesn't belong to the core docs area as well. I am not sure how to deal with this, the best idea I have is to place a short description about why a11y is important and then provide a link to this detailed guide hosted on VueCommunity or as a standalone website (similarly to what we have for Vuex, Vue Router etc.)
Great point @NataliaTepluhina. What do you think if we created an in-depth guide similar to ssr.vuejs.org at a11y.vuejs.org instead? This way we can provide both beginner and advanced guidance to creating accessible applications with Vue. |
|
@bencodezen this would be great! |
Personally I'm not sure about this. One of the problems we have to deal with at the moment is how fragmented the official docs are—we have a dedicated site for almost every official library/technique: ssr, cli, vue-router, vuex, test utils, loader… While there's a premise to this approach, it's been creating quite a heavy burden on maintenance (latest issue was SSR docs which we didn't even know who the maintainers were) and making it hard for users (including me, who's been googling our own resources for references). I would instead try to keep things in one place instead, unless it's a remarkably different system on its own (e.g. VuePress). Granted, it would require thorough (re)thinking on the site structure and make the site much bigger, but it'd fix the abovementioned problems. |
|
On this front btw, I really like how React tackles the topic: keeping everything on one page with focus on React-related techniques but still providing other general information (though mostly as external resources). Maybe we should get some inspiration from that? |
|
If we allow for a full site dedicated to accessibility, this would be a better jump off point for users because this allows for full creative direction of our accessibility team / subject matter experts. I have looked at both the React and Angular a11y guides and while it was okay, it doesn't go all that deep. As far as the fragmentation goes, I don't think the answer to this is to keep this all in a single repository. I cannot speak for others, but I honestly have limited a11y knowledge and wouldn't be able to contribute much as far as open issues / pull requests should anyone want to add anything; so it wouldn't necessarily make things easier to add on to the existing maintenance we will have with Vue 2 + 3 docs moving forward. If anything, we just need to create more structure around the team so it's clear who manages what and anyone can find out via like an organizational chart or something. In addition, by providing the Vue a11y SMEs a way to create a branded experience for learning a11y, I see this as a potential resource that becomes worth mentioning even if you're not fully invested in Vue (just like how many people found the Vue.js docs useful for other things). For example, they can have their own cookbook, or even separate guides for non-library vs library developers. |
|
The whole argument of having a dedicated site being a better dev resource is based on the assumption that we'll have lots to put there along with the resource to maintain it. However, at least for the time being, there's no premise to this assumption. It might very well be just another fragment with little content, adding more into the already fragmented official ecosystem we have. For your concerns regarding docs maintenance, I honestly don't think having a11y as a separate site would make any difference: We'd still need someone experienced with the topic on the docs team anyway. On the contrast, having a11y as part of the main docs has an advantage that everyone would have better visibility on open issues/PRs. For example, though I'm not anywhere close to an a11y expert, if I see an open issue I can always do some initial research and/or involve @mlama007. A separate site wouldn't have this advantage because it would be out of my radar. So I'd still insist that, for a start, it's better to keep things simple by keeping it here in the official docs. If it grows and demands a dedicated site, awesome, let's do it! The fact that it's all md-based should make it trivial to spin off a new Vue/VitePress site anytime. Until then, let's worry about a problem when it becomes one. |
|
@phanan @bencodezen My 2 cents: We're not following React docs step by step; we have our own structure with a short description on the topic not related directly with Vue core and providing a link to a detailed description. I don't think covering all-and-everything in the core docs is a good idea. It's hard to maintain and keep up-to-date. More to say, in particular a11y case I have a feeling all framework docs are repeating the same points with a few framework-specific examples on top. |
I disagree. Unlike other efforts, I am confident in @mlama007's ability to serve as the lead on this initiative and ensure it will be taken care of.
This is true in that everyone would have visibility on it. While it would be great if we could house everything in house, we do not have the capacity as a team to manage all of the docs across the ecosystem at this time. As a result, the scalable solution was to put the team leads on those products (i.e., Router, Vuex, CLI) to manage their own docs. Perhaps one day this could be a good solution when we have a dedicated resource (i.e., full time job) on managing docs; but from what I've observed, we are already buried in work as it is.
If helping to maintain docs across these different projects is important to you, I don't think anyone would have a problem with adding you to the team so you could still get notifications on these individual projects.
The reason an alternative site is being proposed is not because it is the simpler solution; but because it sets a precedence for other topics. For example, if we allow a11y to generate a large scale guide on the Vue.js Guide site, then this opens doors for an entire Testing section which would very quickly make everything unmanageable. And then from there, should we dedicate a section to Performance? And then what comes next? To @NataliaTepluhina's point, until we have a well researched plan for housing everything under one roof, keeping the Vue.js Guide focused on Vue specific things (with recommendations of places to jump off to recommended resources) seems to keep with the values and principles that made the docs as beloved by the public as it is. |
And it's not what I suggested, either. It's an extreme case that I have no intention to suggest. I'm suggesting a balance (only "remarkably different system," to quote myself). Honestly, I do think some of the current dedicated sites should be merged, too, but I'm fine with leaving them as-is for now to not complicate the situation.
I'm not any less confident in her skills, but we're talking about the future. A future is unknown. So however much our confidence is, it's still an assumption. Not to mention, the success of an initiative oftentimes depends on a lot more than just the skills of an individual.
That's not really my point. It's not about me personally, but it would apply to everyone else. If we simply add more and more people into the "a11y" team, in the end, what difference would it make between such a team and the existing doc team?
And that's a precedence I'd very much not want to happen without careful consideration, for every reason I've mentioned. Let's take an example: We have a "Security" section as well. In fact, I am pro-a11y addition partly because I see Security and A11y very similar—they're both topics on top of Vue that can benefit the users yet are often neglected. Now if we have a dedicated site for a11y, why not another one for Security? While we're there, might as well go for TypeScript support as well, right? Sooner or later we'd just spin off subdomains at will and end up with exactly the situation I'd like to avoid by having this conversation. |
|
I think the misalignment here has to do with what we seem to define as the purpose of the vuejs.org/guide site. Correct me if I'm wrong, but you seem to be proposing that it should house all things Vue.js related and go beyond it (to even provide explicit guidance on application topics beyond Vue.js that are arguably simply good practices to have as a developer regardless of framework). However, given what I've seen of the docs up to this point, the purpose of the Vue.js Guide is to provide official guidance on the core library and limited guidance on everything else.
Perhaps what I didn't successfully communicate is that the precedence has already been set. Until we have a more structured plan in place, the Vue.js Guide is meant to provide support to core features only. And then when people need some pointers in another direction, we help nudge them in the right direction, but that is all. I appreciate your suggestion at a new direction; but this would go beyond the scope of the docs team and I think would require a larger scale discussion because this would drastically change how things are currently done. |
Oops. Reading these I've realized I wasn't making myself clear, hence our (seems to be heated) disagreement. Sorry! Let me try it again 😬
I hope my argument is clearer now 😅. |
|
@phanan I disagree with On the contrary, proposed a11y doc focuses a lot on things not related to Vue. I hope this explanation will make my concern more clear. |
|
@NataliaTepluhina I agree, if we put Security and A11y under the light in your argument they're very different: Security is tightly related to Vue, and a11y is not. The question then would be: Why should a11y not be? Why is it so different from Security, i.e. why shouldn't Security be treated the same (focuses on things not related to Vue)? What makes a11y so special in this context? Here I'd like to go back to your initial suggestion: to keep the a11y section on Vue-related matters only, and introduce an introductory paragraph. I found it very sensible and time-fitting. |
I agree that we should limit the number of subdomains we are creating; but a11y is a section that really does deserve its own subdomain given the kinds of resources I have already seem @mlama007 create and believe it provides her (and other a11y focused devs) to have an outlet for their creative ideas and ability to go in depth in ways that go beyond what the current docs can provide. As @NataliaTepluhina has mentioned, the scope of a11y is oftentimes not specific to the core library. And since this is the precedence that we have been working under this entire time, I propose we move on from this by continuing what we've been doing up until this point:
This way we actually publish something that the public can use rather than get caught up with the direction of the site which will take a larger discussion. We can always iterate on this later on. |
It's not that it "shouldn't be." It's more on the objective analysis that the best practices for a11y are not specific to Vue core. It's not like we have specific directives that help you be more accessible. These best practices would largely apply to React and Angular as well. That's why providing a guide that goes over:
Would make a lot more sense as a separate guide. |
|
@bencodezen I believe that if we really dig deep, whatever you said about a11y applies to the other topics I mentioned (Security and TS) as well. That said, your proposal for the time being:
makes perfect sense to me 👍 . |
I have the similar concern here. I'm not sure we have some good enough code samples about like gathering Vue input/output components together as a form for the "Semantics" page. But honestly, in my opinion, the true reason is we didn't have too much Vue-specific experiences on this. As a start, I think non Vue-specific guidelines is still fine. Btw, for the order, I probably prefer putting router-related section later, which means: content structure -> semantics -> routing -> other common missing pieces. WDYT? Then I believe we could accumulate more experiences and improve this progressively. Maybe we could have a dedicated docsite for a11y when we surely have a larger picture about this. And I also believe we have a strong community. So once we release this, we could call for more Vue-specific knowledge and experiences about a11y. And things would become easier I think. Thanks. |
mlama007
force-pushed
the
A11yDocs
branch
2 times, most recently
from
608676e
to
3b66432
Compare
There was a problem hiding this comment.
I think it's worth mentioning that in Vue 2, something like v-bind:aria-checked="false" will produce nothing instead of aria-checked="false", which actually changes the semantics of the attribute. We should suggest developers always stringify boolean values when using aria-* attributes, like v-bind:aria-checked="String(checked)".
Good point! Thankfully this is not the case in Vue 3. Not sure I will include it here, but will def include this in the extended a11y guide for Vue when I go over more advanced use cases. |
|
@mlama007 Oh, you are right, I totally forgot this is for Vue 3! 😆 |
No description provided.