joomla / Manual

Joomla Developer Documentation
28 stars 57 forks source link

Restructure accessibility #285

Closed chmst closed 3 months ago

chmst commented 3 months ago

User description

The part of Accessibility was started big, but we cannot do all this work. It seems better to reduce it all. We should build a library of Code snippets, as we use in Core files, enabling extension developers to see why and how we build accessible views.

@HLeithner this PR is made in version 5.1. Not sure if it is correct with deleting files and folders.


PR Type

Documentation, Enhancement


Description


Changes walkthrough πŸ“

Relevant files
Documentation
13 files
index.md
Enhance accessibility documentation with additional resources and
structure

docs/accessibility/index.md
  • Added links to Joomla's accessibility statement and W3C standards.
  • Included sections on reporting accessibility issues and further
    reading.
  • Improved overall structure and clarity.
  • +19/-2   
    atag.md
    Remove incomplete ATAG conformance documentation                 

    versioned_docs/version-5.1/accessibility/atag.md - Removed unfinished ATAG conformance documentation.
    +0/-12   
    empty-template.md
    Remove empty template for best practices                                 

    versioned_docs/version-5.1/accessibility/best-practices/empty-template.md - Deleted empty template for best practices documentation.
    +0/-61   
    index.md
    Remove placeholder for best practices documentation           

    versioned_docs/version-5.1/accessibility/best-practices/index.md - Removed placeholder for best practices documentation.
    +0/-19   
    tooltip.md
    Remove unfinished tooltip best practices documentation     

    versioned_docs/version-5.1/accessibility/best-practices/tooltip.md - Deleted unfinished tooltip best practices documentation.
    +0/-85   
    code-for-humans.md
    Remove unfinished "code for humans" documentation               

    versioned_docs/version-5.1/accessibility/code-for-humans.md - Removed unfinished "code for humans" documentation.
    +0/-12   
    index.md
    Minor formatting changes to accessible UI library documentation

    versioned_docs/version-5.1/accessibility/element-library/index.md - Minor formatting changes to accessible UI library documentation.
    +1/-1     
    tooltip.md
    Add detailed tooltip best practices documentation               

    versioned_docs/version-5.1/accessibility/element-library/tooltip.md
  • Added detailed tooltip best practices documentation.
  • Included code snippets and common mistakes.
  • Provided examples and relevant WCAG criteria.
  • +75/-0   
    further-reading.md
    Remove placeholder for further reading section                     

    versioned_docs/version-5.1/accessibility/further-reading.md - Removed placeholder for further reading section.
    +0/-12   
    index.md
    Enhance accessibility documentation with additional resources and
    structure

    versioned_docs/version-5.1/accessibility/index.md
  • Added links to Joomla's accessibility statement and W3C standards.
  • Included sections on reporting accessibility issues and further
    reading.
  • Improved overall structure and clarity.
  • +19/-2   
    reporting-issues.md
    Remove unfinished reporting issues documentation                 

    versioned_docs/version-5.1/accessibility/reporting-issues.md - Removed unfinished reporting issues documentation.
    +0/-12   
    testing.md
    Remove unfinished testing accessibility documentation       

    versioned_docs/version-5.1/accessibility/testing.md - Removed unfinished testing accessibility documentation.
    +0/-14   
    wcag.md
    Remove unfinished WCAG conformance documentation                 

    versioned_docs/version-5.1/accessibility/wcag.md - Removed unfinished WCAG conformance documentation.
    +0/-12   

    πŸ’‘ PR-Agent usage: Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

    codiumai-pr-agent-pro[bot] commented 3 months ago

    PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

    PR Reviewer Guide πŸ”

    ⏱️ Estimated effort to review: 2 πŸ”΅πŸ”΅βšͺβšͺβšͺ
    πŸ§ͺ No relevant tests
    πŸ”’ No security concerns identified
    ⚑ Key issues to review

    Typographical Errors
    There are several typographical errors in the added content, such as "infomation" should be "information", "accessibilty" should be "accessibility", and "Detailled" should be "Detailed". Code Snippet Language
    The language specified in the code snippets is 'PHPx', which might be incorrect or non-standard. Consider using 'php' if these are PHP code snippets.
    codiumai-pr-agent-pro[bot] commented 3 months ago

    PR-Agent was enabled for this repository. To continue using it, please link your git user with your CodiumAI identity here.

    PR Code Suggestions ✨

    CategorySuggestion                                                                                                                                    Score
    Maintainability
    Correct spelling mistakes to enhance document professionalism ___ **Correct the spelling mistake in 'infomation' to 'information'.** [docs/accessibility/index.md [13]](https://github.com/joomla/Manual/pull/285/files#diff-e5da3514ace90509b1f0f5eaf2355bd25bb404c0b223cda67aa028230b5968f7R13-R13) ```diff -The infomation in this chapter enables extension and template developers adapting or writing code and keep accessibilty over the whole site. +The information in this chapter enables extension and template developers adapting or writing code and keep accessibility over the whole site. ``` - [ ] **Apply this suggestion**
    Suggestion importance[1-10]: 10 Why: Correcting spelling mistakes is crucial for maintaining professionalism and clarity in documentation.
    10
    Accessibility
    Add descriptive alt-text to images for better accessibility ___ **Add alt-text for images to follow accessibility guidelines and provide context for
    screen readers.** [versioned_docs/version-5.1/accessibility/element-library/tooltip.md [51]](https://github.com/joomla/Manual/pull/285/files#diff-e917ae578c9ba1e1fc28352a372b36e856a21608f39f578523fba8b6738b449eR51-R51) ```diff -![A tooltip indicates the unpublish action on the state button](image.png) +![A tooltip indicates the unpublish action on the state button](image.png "Unpublish action tooltip") ``` - [ ] **Apply this suggestion**
    Suggestion importance[1-10]: 10 Why: Adding alt-text to images is essential for accessibility, ensuring that screen readers can provide context to visually impaired users.
    10
    Enhancement
    Convert plain URLs to Markdown links for better readability ___ **Replace the plain URL with a Markdown link to improve readability and user
    experience.** [docs/accessibility/index.md [8]](https://github.com/joomla/Manual/pull/285/files#diff-e5da3514ace90509b1f0f5eaf2355bd25bb404c0b223cda67aa028230b5968f7R8-R8) ```diff -Find here Joomla's accessibility Statement https://www.joomla.org/accessibility-statement.html. +Find here Joomla's accessibility Statement [here](https://www.joomla.org/accessibility-statement.html). ``` - [ ] **Apply this suggestion**
    Suggestion importance[1-10]: 9 Why: The suggestion improves readability and user experience by converting plain URLs to Markdown links, which is a best practice in documentation.
    9
    Best practice
    Clarify how to make tooltips dismissible to comply with accessibility standards ___ **Ensure that the tooltip text is dismissible and does not disappear automatically by
    adding a clear example or guideline.** [versioned_docs/version-5.1/accessibility/element-library/tooltip.md [16]](https://github.com/joomla/Manual/pull/285/files#diff-e917ae578c9ba1e1fc28352a372b36e856a21608f39f578523fba8b6738b449eR16-R16) ```diff -The tooltip must be dismissible, cannot disappear automatically. +Ensure that tooltips are dismissible and do not disappear automatically. For example, add a close button or allow dismissal through keyboard interactions. ``` - [ ] **Apply this suggestion**
    Suggestion importance[1-10]: 8 Why: The suggestion provides a clear guideline on how to make tooltips dismissible, which is important for accessibility compliance.
    8
    HLeithner commented 3 months ago

    In general please don't edit old versions only edit /docs, afterwards we (you, me anyone else) can backport it older versions.

    Also I'm a bit confused you added a template (which shouldn't be at this place) but then don't use it? is that expected?

    I think also it's important to explain some basics of a11y, I know that topic is really complex but there are low hanging fruits which many developers or designers fails on which can easily be solved. Like contrasts or Link text, and size, nothing special but just to give a show introduction why things are how they are.

    Also please follow the coding guide for the Documention, we don't allow more then one h1 in the documentation which is actually the first headline with is unterlined with =. All other Headline starts with at least 2 #.