mirrors/django
1
0
Fork 0
mirror of https://github.com/django/django.git synced 2025-11-19 03:08:59 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

Add guidelines for accessibility in documentation

Browse source 
Co-authored-by: Scott Cranfill <scott@scottcranfill.com>
This commit is contained in:
Thibaud Colas 2023-10-05 07:21:21 +01:00
parent 45ba7683a6
commit c1c07e264d
1 changed files with 22 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

22
docs/internals/contributing/writing-documentation.txt
View file

@ -213,6 +213,10 @@ point to the latest or stable version of the documentation, e.g. ``/en/stable/``
Writing style
=============
Prefer plain language. Avoid jargon and technical terms unless
they are necessary. Keep sentences short and to the point. Use the active voice
where possible.
When using pronouns in reference to a hypothetical person, such as "a user with
a session cookie", gender-neutral pronouns (they/their/them) should be used.
Instead of:
@ -622,6 +626,24 @@ you'd like to help translate the documentation into another language.
.. _django-admin-manpage:
Accessibility in documentation
==============================
See :doc:`/internals/contributing/accessibility` for our project guidelines. For documentation
specifically, guide readers to use accessible patterns. This means documentation should:
* Include enough code so examples are accessible by default.
* Start with the accessible way when showcasing multiple options.
* Prefer semantic HTML elements over ARIA attributes.
Here are practical examples of those guidelines:
* Forms should use :meth:`.Form.as_div` over less accessible alternatives.
* Images should have alternative text with the ``alt`` attribute.
* ``<html>`` elements must have a ``lang`` attribute.
* Use semantic headings instead of bold or styled text.
* Demonstrate ``dialog`` or ``details`` elements over their ARIA equivalents.
``django-admin`` man page
=========================