Re: Admin accessibility

[Thibaud Colas]

Hi all,

Now that the DEP PR has been submitted I was wondering what the next steps 
would be. According to the documented DEP process I found, it’s at the "forming 
the team" 
<https://github.com/django/deps/blob/master/final/0001-dep-process.rst#forming-the-team>
 
stage? How do you go about creating an *Implementation Team* and finding a 
*Shepherd*?

The main reason I ask is that I’ll be giving a talk about accessibility at 
DjangoCon EU in a couple of weeks, and I thought it would be a good 
occasion to raise awareness of the issues with the Django admin, and 
mention this DEP. But I want to make sure I provide accurate information.

Thanks in advance,

Thibaud

On Tuesday, 14 July 2020 at 09:37:01 UTC+1 Thibaud Colas wrote:

>  it’s wonderful to see this happening! Re-reading through the whole 
> thing, as Tobias mentioned I also find it very easy to read, and makes a 
> good case.
>
> On Tuesday, 14 July 2020 at 09:24:15 UTC+1 t...@carrick.eu wrote:
>
>> I've added a PR to the DEPs repo to hopefully get some eyes on it: 
>> https://github.com/django/deps/pull/69
>>
>> Thibaud, I think whatever you have the time and motivation for sounds 
>> good, all of those things are useful. If you're not sure about all the 
>> admin features, I think that's pretty normal. One project I've had on my 
>> mind for a while now is to build a simple django site that is essentially 
>> just there to use every feature of the admin, so I might bump that up the 
>> priority list, though it's somewhat daunting.
>>
>> Cheers,
>> Tom
>>
>> On Mon, 13 Jul 2020 at 01:15, Thibaud Colas  wrote:
>>
>>> Update for the proof of concept CI tests from my side – thank you Tom 
>>> for the feedback. Here are the latest additions to the test suite & 
>>> reports, still living at 
>>> https://thibaudcolas.github.io/django_admin_tests/,
>>>
>>> - Added as much as I know about in the admin, and now also outside of it 
>>> a bit (startproject welcome page, error pages)
>>> - Separated the issues between Axe and HTML_CS so the numbers are easier 
>>> to understand
>>> - Added anchor links everywhere for easier navigation
>>> - I’ve also started a draft list of "things to (potentially) audit", 
>>> over at 
>>> https://github.com/thibaudcolas/django_admin_tests#scope-for-future-audits
>>>
>>> I think the next two big steps are what you mention:
>>>
>>> - Having a way to track the number of issues over time. Currently the 
>>> report overwrites itself every week (well, every build). If you have a 
>>> suggestion on ways to demo this that would be useful please let me know. 
>>> Currently I’m thinking sparklines for each test case could be nice as a 
>>> proof of concept, and a sparkline for the total number of issues. Or see 
>>> whether I should get out of my comfort zone a bit and find a 
>>> dashboard/graphing tool to send the metrics to and graph there.
>>> - Testing more features of modeladmin. I don’t use it too frequently 
>>> myself so don’t really know what’s “easy” to enable – if you know of an 
>>> existing test suite I could repurpose, or of an example of using a lot of 
>>> functionality – I’d be keen to invest time to add it to my test site.
>>>
>>> Alternatively something else I could do is to file a ticket for 
>>> accessibility issues with the welcome page – I’ve tested it with screen 
>>> readers, there are a few issues, but nothing that should be too hard to 
>>> fix, and it might be a good demo of what reporting accessibility issues in 
>>> general could look like?
>>>
>>> Cheers,
>>>
>>> Thibaud
>>>
>>>
>>> On Tuesday, 30 June 2020 at 18:59:53 UTC+1 Tobias Bengfort wrote:
>>>
>>>> Nice writeup! I found it easy to read (I did not catch myself skipping 
>>>> paragraphs which is always a good sign). Contentwise, I would have no 
>>>> issue if this was accepted as is. Maybe I am forgetting about some 
>>>> important details though. 
>>>>
>>>> I had just some ideas that might be good additions: 
>>>>
>>>> - mention ATAG somewhere 
>>>>
>>>> - It would be nice to have a real commitment to accessibility. 
>>>> Something 
>>>> along the lines of "accessibility bugs must be treated with the same 
>>>> priority as any other bugs". 
>>>>
>>>> - The step from "leaving accessibility in the hands of 
>>>> individual contrib

Re: Admin accessibility

[Thibaud Colas]

I’d love to! But worth bearing in mind that I haven’t done any Django 
contributions before.

I decided to end my talk with a call for feedback on your DEP – this feels 
like the ideal call to action to end on.

On Monday, 14 September 2020 at 18:00:03 UTC+1 t...@carrick.eu wrote:

> Carlton, I think that would be useful, thanks.
>
> Thibaud, shall I add you to the implementation team? It seems like you're 
> doing more work on this than I am lately. I think we could still use one or 
> perhaps two more people, but I think it's a good start.
>
> On Mon, 14 Sep 2020 at 16:44, Carlton Gibson  wrote:
>
>> Hi All. 
>>
>> Thanks for this. I'd be happy to play *Shepherd *if you need someone to 
>> put their hand up. 
>> I think that means I need to nag about getting it done. So... 
>>
>> Who's going to be on the team to do the first review, and then subsequent 
>> work? Answer that and you have the Implementation Team. 
>> I like that you've thought about how the team can refresh periodically — 
>> I don't suppose the burden will be too great but folks tend to cycle-out 
>> naturally, so good to plan for that. 
>> Thibaud: Asking for hands in your talk seems sensible. 
>>
>> Kind Regards,
>>
>> Carlton
>>
>>
>>
>> On Sunday, 6 September 2020 at 00:45:36 UTC+2 Thibaud Colas wrote:
>>
>>> Hi all,
>>>
>>> Now that the DEP PR has been submitted I was wondering what the next 
>>> steps would be. According to the documented DEP process I found, it’s at 
>>> the "forming the team" 
>>> <https://github.com/django/deps/blob/master/final/0001-dep-process.rst#forming-the-team>
>>>  
>>> stage? How do you go about creating an *Implementation Team* and 
>>> finding a *Shepherd*?
>>>
>>> The main reason I ask is that I’ll be giving a talk about accessibility 
>>> at DjangoCon EU in a couple of weeks, and I thought it would be a good 
>>> occasion to raise awareness of the issues with the Django admin, and 
>>> mention this DEP. But I want to make sure I provide accurate information.
>>>
>>> Thanks in advance,
>>>
>>> Thibaud
>>>
>>> On Tuesday, 14 July 2020 at 09:37:01 UTC+1 Thibaud Colas wrote:
>>>
>>>>  it’s wonderful to see this happening! Re-reading through the whole 
>>>> thing, as Tobias mentioned I also find it very easy to read, and makes a 
>>>> good case.
>>>>
>>>> On Tuesday, 14 July 2020 at 09:24:15 UTC+1 t...@carrick.eu wrote:
>>>>
>>>>> I've added a PR to the DEPs repo to hopefully get some eyes on it: 
>>>>> https://github.com/django/deps/pull/69
>>>>>
>>>>> Thibaud, I think whatever you have the time and motivation for sounds 
>>>>> good, all of those things are useful. If you're not sure about all the 
>>>>> admin features, I think that's pretty normal. One project I've had on my 
>>>>> mind for a while now is to build a simple django site that is essentially 
>>>>> just there to use every feature of the admin, so I might bump that up the 
>>>>> priority list, though it's somewhat daunting.
>>>>>
>>>>> Cheers,
>>>>> Tom
>>>>>
>>>>> On Mon, 13 Jul 2020 at 01:15, Thibaud Colas  
>>>>> wrote:
>>>>>
>>>>>> Update for the proof of concept CI tests from my side – thank you Tom 
>>>>>> for the feedback. Here are the latest additions to the test suite & 
>>>>>> reports, still living at 
>>>>>> https://thibaudcolas.github.io/django_admin_tests/,
>>>>>>
>>>>>> - Added as much as I know about in the admin, and now also outside of 
>>>>>> it a bit (startproject welcome page, error pages)
>>>>>> - Separated the issues between Axe and HTML_CS so the numbers are 
>>>>>> easier to understand
>>>>>> - Added anchor links everywhere for easier navigation
>>>>>> - I’ve also started a draft list of "things to (potentially) audit", 
>>>>>> over at 
>>>>>> https://github.com/thibaudcolas/django_admin_tests#scope-for-future-audits
>>>>>>
>>>>>> I think the next two big steps are what you mention:
>>>>>>
>>>>>> - Having a way to track the number of issues over time. Currently the 
>>>>>> report overwrites itself every week (well, every bu

Re: Admin accessibility

[Thibaud Colas]

Hi Tom,

It’s exciting to see this getting started! To me a DEP would be highly 
beneficial, because there is a lot to this that goes beyond finding and 
fixing individual issues – it’s more about detailing the a process for 
parts of Django to stay accessible over time. Here are things I’d suggest 
to cover, in addition to your list:

- Going further than the targeted standard and tests in CI –  outline clear 
steps developers should take when testing their work: using developer 
tools, screen readers, etc. It’s not practical to just state the standard 
as WCAG is quite big, and open to interpretation. And CI testing will never 
be enough to reach any degree of compliance.
  - I’m not familiar with Django’s development process but generally I 
would recommend to use a combination of linting, browser extensions, manual 
testing instructions – and CI tests.
- If the accessibility team was to cover more than the Django admin, I 
think it would be worthwhile to also include accessibility of sites built 
with Django. Django is largely unopinionated about markup, but I remember 
its forms markup not being particularly good for screen readers, and the 
HTML code snippets in the docs would also be worth reviewing.
- Same goes for admin docs – not too familiar with them myself so I’m not 
sure whether they are considered to be part of the admin, or separate.
- I wouldn’t find it surprising if an audit of the Django admin turned up a 
lot of issues. IMHO part of the DEP should cover how to manage this – 
whether individual issues warrant individual tickets or not, and how to 
prioritize the issues if relevant. Which kinds of issues are likely to need 
design input. If the DEP is done first, also talk about what kind of 
auditing would be valuable, and how to make it happen.

To help with the initial audit and prioritisation of issues, I would 
suggest to first start by creating a map of all of the parts of the Django 
admin that are to be audited – list all of the individual pages, and all of 
the states the pages can be in (success, error, loading – empty content / 
some content / paginating, etc). I also find it worthwhile to add a 
succinct definition of how each of those pages is likely to be used – for 
example things that are only configured once for a site’s lifetime are 
presumably not as worth improving as a screen a user would see on a daily 
basis. Here is an example in practice: 
https://docs.google.com/spreadsheets/d/1rTMilzKhcb43Y3fZKGJJeoKWLCR00bfgwVB9f6OaC2U/edit
 
.
 
This can also be used to track the auditing effort, and form the basis of 
an automated test suite for CI (or simply repeat testing).

Finally, consider ATAG2.0  (Authoring Tool 
Accessibility Guidelines) compliance additionally to WCAG. At a high level, 
ATAG is made of two parts:

- Part A: Make the authoring tool user interface accessible. That sounds 
like what we’re discussing here.
- Part B: Support the production of accessible content. That’s a whole 
other topic but feels relevant too.

ATAG is nowhere near as well known / established / easy to test for, but it 
feels very relevant to the Django admin in particular, and I’m sure there 
will at least be some useful bits to consider in its success criteria

Hope this helps!

Thibaud


On Monday, May 25, 2020 at 11:56:39 AM UTC+1, Tom Carrick wrote:
>
> Hi,
>
> Thanks for the feedback. I had thought about a DEP when I was writing up 
> the original post actually, I just wasn't sure what it should contain. Here 
> are my thoughts, based on the feedback so far:
>
> - Defining a standard to target.
> - Forming an a11y team that covers the django admin and all sites in the 
> django github organization, and defining its role, membership, etc.
> - Deciding on a CI process
> - An outline of current issues and how to solve them.
>
> If anyone can think of anything else, please let me know. If/when there's 
> a consensus I'll start writing a draft.
>
> Mariusz, I mentioned this in the original post, but 
> https://www.w3.org/WAI/policies/ has a good overview of laws and EU 
> directives in this area. From my browsing through, it seems that they all 
> either, have their own national standard, or are using WCAG 2.0/2.1 AA. 
> Since we probably don't want to define our own standard, I think AA is the 
> way to go. This seems to also be the recommendation I hear from people in 
> the accessibility field working on regular websites. AAA seems to be more 
> suited for very specialist sites that explicitly target disabled people.
>
> Most of AAA is completely feasible for us, but there are some reasons it 
> would be difficult:
>
> - All language needs to be at a lower secondary education level, or have 
> an alternative that is. This doesn't seem feasible, for e.g. the 
> documentation.
> - Users that are logged out need to be able to resume their session where 
> 

Re: Admin accessibility

[Thibaud Colas]

Hi all,

I’m also interested in helping with this, although I’ve never been involved 
with Django development before. I’ve recently worked on a similar accessibility 
effort for Wagtail , a CMS built 
upon Django, which largely replaces the Django admin interface on projects 
where it’s used – and thus has similar use cases and audiences. We 
discussed which standards to aim for, why, which tools to use when, what to 
expect of contributors, etc, which I believe would be similarly relevant to 
Django. If Django had done this before we’d definitely have borrowed from 
its approach :)

I would recommend Pa11y  as a tool to 
consider adding in CI. It uses HTML CodeSniffer and Axe under the hood 
(similarly to Lighthouse), which both score relatively well in how many 
issues they find. As Kye mentions this only goes so far (30-40% of issues 
at most ), but still 
helpful to have automated checks if possible.

Cheers,

Thibaud



On Tuesday, 19 May 2020 12:12:17 UTC+1, Tom Carrick wrote:
>
> Sorry, long post incoming.
>
> The admin currently has some accessibility issues. Not a huge amount, 
> actually, but they should be fixed regardless. I hope I don't need to 
> convince anyone here of the importance of accessibility, but I'll try to 
> make the case as briefly as possible for the benefit of the wider community.
>
> There is a trend towards stronger accessibility laws - there is a good 
> roundup of them here: https://www.w3.org/WAI/policies/ - and I'll come 
> back to this later. Most of these cover the public sector and small 
> segments of the private sector, but there's also an overview of some laws 
> used against private entities more generally here: 
> https://en.wikipedia.org/wiki/Web_Content_Accessibility_Guidelines#Legal_obligations
>
> I should make it clear that I'm not a lawyer and have no idea if any of 
> this would apply to the admin, since it's not intended for general 
> consumption, so I think I'd rather make this point: Developers and other 
> people using the admin - "staff users" of some kind - can have disabilities 
> too, and we should be catering for them, especially since the remedies are 
> not at all difficult. It's also worth pointing out that accessibility 
> improvements almost always improve the general experience. For example, 
> making sure everything is easily accessible for keyboard only users is also 
> beneficial to power users. Better contrast and larger fonts are more 
> legible for everyone, not just for those with low vision, etc.
>
> So I think the place to start here is to decide on a guideline to aim for, 
> and I'm pretty convinced at this point that WCAG 2.1 at Level AA is the way 
> to go: https://www.w3.org/TR/WCAG21/
>
> Why not AAA? Well, it's really hard / time-consuming. For example, users 
> have to be able to select their own foreground / background colours, if a 
> user's session expires, they need to be able to login in again and pick off 
> where they left off (forms filled, etc.), and more. Moreover, every law 
> I've looked at seems to use WCAG 2.0 (2.1 is just a couple years old and is 
> backwards compatible) at Level AA, so this seems like the target to aim 
> for. I don't see a reason to not make specific improvements to AAA where 
> they're relatively simple, however, but my point is that we should make AA 
> a minimum requirement.
>
> So if that is accepted, we need a few things:
>
> 1. Document it and update the contributing docs.
> 2. Audit the admin properly.
> 3. Fix any issues.
> 4. Make sure reviewers have this in mind for admin changes (I'm not sure 
> if there's any CI solution for this, but it would be nice to have).
>
> I haven't audited the entire admin, but I have run a checker through some 
> pages. The main issues are with contrast and small font sizes, and the 
> changelist also seems quite painful. For example, there are no labels on 
> the checkboxes to select rows, which is going to be pretty hard to 
> understand and use if you're blind. A quick aria-label can fix this without 
> affecting it for sighted users.
>
> Another issue here is harder to solve, it requires two tabs to move to 
> another row of the change list in the default state (one for the checkbox, 
> one for the link to the change form page). If you have editable fields in 
> the change list, it's another tab for each. It would be nice to be able to 
> use vim keys to move up and down rows, perhaps be able to hit * to select a 
> row for an action. In general, keyboard shortcuts would be handy elsewhere 
> too. It would be nice to be able to hit a key to open the nav sidebar which 
> also sets tab focus on the first link, for example.
>
> But these details aren't the point of the post. The point of the post is 
> to decide if this is worth it (clearly I think it is), and how to move 
> forwards on it. Any thoughts?
>

-- 
You received 

Re: Admin accessibility

[Thibaud Colas]

 it’s wonderful to see this happening! Re-reading through the whole 
thing, as Tobias mentioned I also find it very easy to read, and makes a 
good case.

On Tuesday, 14 July 2020 at 09:24:15 UTC+1 t...@carrick.eu wrote:

> I've added a PR to the DEPs repo to hopefully get some eyes on it: 
> https://github.com/django/deps/pull/69
>
> Thibaud, I think whatever you have the time and motivation for sounds 
> good, all of those things are useful. If you're not sure about all the 
> admin features, I think that's pretty normal. One project I've had on my 
> mind for a while now is to build a simple django site that is essentially 
> just there to use every feature of the admin, so I might bump that up the 
> priority list, though it's somewhat daunting.
>
> Cheers,
> Tom
>
> On Mon, 13 Jul 2020 at 01:15, Thibaud Colas  wrote:
>
>> Update for the proof of concept CI tests from my side – thank you Tom for 
>> the feedback. Here are the latest additions to the test suite & reports, 
>> still living at https://thibaudcolas.github.io/django_admin_tests/,
>>
>> - Added as much as I know about in the admin, and now also outside of it 
>> a bit (startproject welcome page, error pages)
>> - Separated the issues between Axe and HTML_CS so the numbers are easier 
>> to understand
>> - Added anchor links everywhere for easier navigation
>> - I’ve also started a draft list of "things to (potentially) audit", over 
>> at 
>> https://github.com/thibaudcolas/django_admin_tests#scope-for-future-audits
>>
>> I think the next two big steps are what you mention:
>>
>> - Having a way to track the number of issues over time. Currently the 
>> report overwrites itself every week (well, every build). If you have a 
>> suggestion on ways to demo this that would be useful please let me know. 
>> Currently I’m thinking sparklines for each test case could be nice as a 
>> proof of concept, and a sparkline for the total number of issues. Or see 
>> whether I should get out of my comfort zone a bit and find a 
>> dashboard/graphing tool to send the metrics to and graph there.
>> - Testing more features of modeladmin. I don’t use it too frequently 
>> myself so don’t really know what’s “easy” to enable – if you know of an 
>> existing test suite I could repurpose, or of an example of using a lot of 
>> functionality – I’d be keen to invest time to add it to my test site.
>>
>> Alternatively something else I could do is to file a ticket for 
>> accessibility issues with the welcome page – I’ve tested it with screen 
>> readers, there are a few issues, but nothing that should be too hard to 
>> fix, and it might be a good demo of what reporting accessibility issues in 
>> general could look like?
>>
>> Cheers,
>>
>> Thibaud
>>
>>
>> On Tuesday, 30 June 2020 at 18:59:53 UTC+1 Tobias Bengfort wrote:
>>
>>> Nice writeup! I found it easy to read (I did not catch myself skipping 
>>> paragraphs which is always a good sign). Contentwise, I would have no 
>>> issue if this was accepted as is. Maybe I am forgetting about some 
>>> important details though. 
>>>
>>> I had just some ideas that might be good additions: 
>>>
>>> - mention ATAG somewhere 
>>>
>>> - It would be nice to have a real commitment to accessibility. Something 
>>> along the lines of "accessibility bugs must be treated with the same 
>>> priority as any other bugs". 
>>>
>>> - The step from "leaving accessibility in the hands of 
>>> individual contributors" to "you have to commit for 9 months" is a tad 
>>> big. I keep wondering if we can do something to improve the options in 
>>> between those. One idea would be to formalize an "a11y" keyword so 
>>> interested contributors can easily find related tickets. 
>>>
>>> tobias 
>>>
>> -- 
>>
> You received this message because you are subscribed to the Google Groups 
>> "Django developers (Contributions to Django itself)" group.
>> To unsubscribe from this group and stop receiving emails from it, send an 
>> email to django-develop...@googlegroups.com.
>>
> To view this discussion on the web visit 
>> https://groups.google.com/d/msgid/django-developers/e65e3879-d74c-4401-9232-29eb0a73385cn%40googlegroups.com
>>  
>> <https://groups.google.com/d/msgid/django-developers/e65e3879-d74c-4401-9232-29eb0a73385cn%40googlegroups.com?utm_medium=email_source=footer>
>> .
>>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/6e323a74-38a7-4c64-9b22-4c71c6410056n%40googlegroups.com.

Re: Admin accessibility

[Thibaud Colas]

Update for the proof of concept CI tests from my side – thank you Tom for 
the feedback. Here are the latest additions to the test suite & reports, 
still living at https://thibaudcolas.github.io/django_admin_tests/,

- Added as much as I know about in the admin, and now also outside of it a 
bit (startproject welcome page, error pages)
- Separated the issues between Axe and HTML_CS so the numbers are easier to 
understand
- Added anchor links everywhere for easier navigation
- I’ve also started a draft list of "things to (potentially) audit", over 
at 
https://github.com/thibaudcolas/django_admin_tests#scope-for-future-audits

I think the next two big steps are what you mention:

- Having a way to track the number of issues over time. Currently the 
report overwrites itself every week (well, every build). If you have a 
suggestion on ways to demo this that would be useful please let me know. 
Currently I’m thinking sparklines for each test case could be nice as a 
proof of concept, and a sparkline for the total number of issues. Or see 
whether I should get out of my comfort zone a bit and find a 
dashboard/graphing tool to send the metrics to and graph there.
- Testing more features of modeladmin. I don’t use it too frequently myself 
so don’t really know what’s “easy” to enable – if you know of an existing 
test suite I could repurpose, or of an example of using a lot of 
functionality – I’d be keen to invest time to add it to my test site.

Alternatively something else I could do is to file a ticket for 
accessibility issues with the welcome page – I’ve tested it with screen 
readers, there are a few issues, but nothing that should be too hard to 
fix, and it might be a good demo of what reporting accessibility issues in 
general could look like?

Cheers,

Thibaud


On Tuesday, 30 June 2020 at 18:59:53 UTC+1 Tobias Bengfort wrote:

> Nice writeup! I found it easy to read (I did not catch myself skipping
> paragraphs which is always a good sign). Contentwise, I would have no
> issue if this was accepted as is. Maybe I am forgetting about some
> important details though.
>
> I had just some ideas that might be good additions:
>
> - mention ATAG somewhere
>
> - It would be nice to have a real commitment to accessibility. Something
> along the lines of "accessibility bugs must be treated with the same
> priority as any other bugs".
>
> - The step from "leaving accessibility in the hands of
> individual contributors" to "you have to commit for 9 months" is a tad
> big. I keep wondering if we can do something to improve the options in
> between those. One idea would be to formalize an "a11y" keyword so
> interested contributors can easily find related tickets.
>
> tobias
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/e65e3879-d74c-4401-9232-29eb0a73385cn%40googlegroups.com.

Re: Admin accessibility

[Thibaud Colas]

Hi Tom,

Great to hear – no rush if you’re busy with other things. Here’s a quick 
proof of concept, with 20 different pages/scenarios, tested with Axe, HTML 
Code Sniffer, and Lighthouse: 
https://github.com/thibaudcolas/django_admin_tests.

I’m not a big fan of Lighthouse personally, and I already had the rest of 
the tools set up, hence why I went with this. I spent a bit of time making 
a report out of the test results, which you can see an example of at 
https://thibaudcolas.github.io/django_admin_tests/. This is generated in 
Travis, currently set up to run those tests & regenerate the report from 
Django’s `master` branch once per week.

I added instructions on the README to run this locally if anyone wants to 
try it out, and a few words about what to make of the report / issues. I 
didn’t look into what the issues were though.

Let me know what you think, and I should be able to spend more time on this 
next week if it helps.

On Wednesday, 24 June 2020 at 09:11:52 UTC+1 t...@carrick.eu wrote:

> A quick update first. I'm pretty busy with a combination of day job and 
> personal projects, but I should have time to start writing the draft DEP in 
> the next week or two.
>
> Thibaud, I think the absolute most important thing is a way to measure 
> progress, even if - as others have mentioned - that measure is imperfect. I 
> think getting a proof of concept of Lighthouse running against a few admin 
> pages would be extremely helpful. It's also probably one of the more 
> difficult things. If that seems like too much, I think catching what the CI 
> would miss is the next most important thing, so I think your #1 suggestion 
> would work well.
>
> On Tue, 23 Jun 2020 at 22:34, Thibaud Colas  wrote:
>
>> Hey Tom,
>>
>> I wanted to check if there is anything we/I could do to help in the 
>> meantime? Whether that’s by starting to map or audit the Django admin, or 
>> setting up a sample CI pipeline with accessibility tests, or something else 
>> altogether. It’s a bit daunting to get started with this but I think I 
>> could realistically do one of:
>>
>> 1. Create a draft map of the Django admin UI for later manual auditing 
>> purposes.
>> 2. Audi a specific part of Django and creating a ticket with concrete 
>> things to fix.
>> 3. Set up static analysis for the CSS or HTML to look for common 
>> accessibility gotchas.
>> 4. Sett up automated in-browser accessibility checks on some parts of 
>> Django to show what that might look like in a CI pipeline.
>>
>> … and document the steps along the way, and report back here or as a 
>> ticket.
>>
>> Cheers,
>>
>> Thibaud
>>
>> On Tuesday, May 26, 2020 at 10:22:26 AM UTC+1, Tom Carrick wrote:
>>>
>>> Some further thoughts...
>>>
>>> Mariusz, I don't think I agree that WCAG is massive. It can look a 
>>> little large but I think that's mostly because each guideline is split into 
>>> smaller pieces and it's quite wordy to avoid ambiguity. There are in 2.1 50 
>>> success criteria for AA, many of which can be checked automatically, and 
>>> many of those that can't don't apply to us as we don't use audio / video. 
>>> There's also a nice quick reference 
>>> <https://www.w3.org/WAI/WCAG21/quickref/> that can be filtered to 
>>> remove AAA and anything else unwanted. Once you drill down it can again get 
>>> quite wordy, but it covers a lot. I think it's worth remembering here is 
>>> that the point is not to strictly adhere to a standard for the sake of it, 
>>> just to improve the overall accessibility, and WCAG is a useful and 
>>> measurable tool to get us some of the way there.
>>>
>>> Thibaud, I more or less agree with everything there. I'm not sure 
>>> developers should have to do full accessibility checks for their changes in 
>>> the admin. Using a screen reader for example can be very frustrating and 
>>> confusing if you're not used to it, and it can take an inordinate amount of 
>>> time, and I don't really wish that burden on (for example) first time 
>>> committers who already have a lot of stuff to do, I think this will only 
>>> discourage contributions. I think it should be the responsibility of the 
>>> accessibility team to provide feedback, suggestions, etc. on relevant PRs 
>>> or fix things when they're noticed after manual audits.
>>>
>>> ATAG looks handy, but at first glance we couldn't even get to A, it 
>>> requires auto-saving. It also generally seems like something that would 
>>> cover a rich text editor plugged into the admin more than the admin itself, 
>>> th

Re: Admin accessibility

[Thibaud Colas]

Hey Tom,

I wanted to check if there is anything we/I could do to help in the 
meantime? Whether that’s by starting to map or audit the Django admin, or 
setting up a sample CI pipeline with accessibility tests, or something else 
altogether. It’s a bit daunting to get started with this but I think I 
could realistically do one of:

1. Create a draft map of the Django admin UI for later manual auditing 
purposes.
2. Audi a specific part of Django and creating a ticket with concrete 
things to fix.
3. Set up static analysis for the CSS or HTML to look for common 
accessibility gotchas.
4. Sett up automated in-browser accessibility checks on some parts of 
Django to show what that might look like in a CI pipeline.

… and document the steps along the way, and report back here or as a ticket.

Cheers,

Thibaud

On Tuesday, May 26, 2020 at 10:22:26 AM UTC+1, Tom Carrick wrote:
>
> Some further thoughts...
>
> Mariusz, I don't think I agree that WCAG is massive. It can look a little 
> large but I think that's mostly because each guideline is split into 
> smaller pieces and it's quite wordy to avoid ambiguity. There are in 2.1 50 
> success criteria for AA, many of which can be checked automatically, and 
> many of those that can't don't apply to us as we don't use audio / video. 
> There's also a nice quick reference 
> <https://www.w3.org/WAI/WCAG21/quickref/> that can be filtered to remove 
> AAA and anything else unwanted. Once you drill down it can again get quite 
> wordy, but it covers a lot. I think it's worth remembering here is that the 
> point is not to strictly adhere to a standard for the sake of it, just to 
> improve the overall accessibility, and WCAG is a useful and measurable tool 
> to get us some of the way there.
>
> Thibaud, I more or less agree with everything there. I'm not sure 
> developers should have to do full accessibility checks for their changes in 
> the admin. Using a screen reader for example can be very frustrating and 
> confusing if you're not used to it, and it can take an inordinate amount of 
> time, and I don't really wish that burden on (for example) first time 
> committers who already have a lot of stuff to do, I think this will only 
> discourage contributions. I think it should be the responsibility of the 
> accessibility team to provide feedback, suggestions, etc. on relevant PRs 
> or fix things when they're noticed after manual audits.
>
> ATAG looks handy, but at first glance we couldn't even get to A, it 
> requires auto-saving. It also generally seems like something that would 
> cover a rich text editor plugged into the admin more than the admin itself, 
> though I think it's laudable as a future target.
>
> The more I think about it, I think the DEP should be a process DEP rather 
> than a feature DEP. As others have mentioned, we don't need a DEP to fix 
> accessibility issues - just fix them. But forming a team seems useful, and 
> I think a DEP is required for that. I think the DEP should be limited to:
>
> 1. The accessibility team, how membership is decided, who it's accountable 
> to, it's role/responsibilities, etc.
> 2. Perhaps the initial standard(s) to target, although this could also be 
> decided by the a11y team post-assembly and agreed with the technical board 
> and/or core devs.
>
> As I said, I'm happy to write up the DEP, but since it'll be a process 
> DEP, I think I'd need the support of a core dev, someone on the technical 
> board, or just someone who has more knowledge of Django's "bureaucracy", 
> for lack of a better word.
>
> Tom
>
> On Tue, 26 May 2020 at 01:20, Thibaud Colas  > wrote:
>
>> Hi Tom,
>>
>> It’s exciting to see this getting started! To me a DEP would be highly 
>> beneficial, because there is a lot to this that goes beyond finding and 
>> fixing individual issues – it’s more about detailing the a process for 
>> parts of Django to stay accessible over time. Here are things I’d suggest 
>> to cover, in addition to your list:
>>
>> - Going further than the targeted standard and tests in CI –  outline 
>> clear steps developers should take when testing their work: using developer 
>> tools, screen readers, etc. It’s not practical to just state the standard 
>> as WCAG is quite big, and open to interpretation. And CI testing will never 
>> be enough to reach any degree of compliance.
>>   - I’m not familiar with Django’s development process but generally I 
>> would recommend to use a combination of linting, browser extensions, manual 
>> testing instructions – and CI tests.
>> - If the accessibility team was to cover more than the Django admin, I 
>> think it would be worthwhile to also include accessibility of sites built 
>> wit

Re: Admin accessibility

[Thibaud Colas]

Hi all,

I know setting up the team is still under way but in the meantime I wanted 
to bring your attention to a set of issues I recently reported about the 
accessibility of Django forms:

- The as_table, as_ul, as_p output styles being inappropriate, 
https://code.djangoproject.com/ticket/32338
- Markup issues with fields based on multiple radio or checkbox, 
https://code.djangoproject.com/ticket/32339
- Usability concerns with text fields that expect specific formatting, 
https://code.djangoproject.com/ticket/32340

Those issues are what I’ve come across the most while working on Django 
sites, and I think are by far what end users are most likely to run into. 
So I thought it would be worthwhile to report the problems sooner rather 
than later, and share it here for others’ consideration. I’d also 
appreciate on what makes for a good issue report for accessibility in 
particular if anyone has feedback on that area – I was quite keen to make 
more screen recordings but the ticket tracker only supports very small 
images and video seemed a bit overkill. But am happy to upload bug reports 
to YouTube if others would value this.

Best regards,

Thibaud

On Thursday, 12 November 2020 at 09:24:22 UTC carlton...@gmail.com wrote:

> Thanks all — I think we're there. 
>
> All positives expressed. Do I need to ensure those who've not 
> commented/voted do so? 
>
>
> One question while we're here: 
>
> * Do we have any specialist designers on board who could help serve on 
> this team? 
> * Related who can I ping ref the design on djangoproject.com? (Who did 
> the design work do we recall? — there are credits at the bottom of the 
> website, but I'm wondering if someone can point me straight to the 
> responsible people?)
>
> Why? Read on... 
>
> So we have this PR on to fix the color contrasts on the main website: 
> https://github.com/django/djangoproject.com/pull/998
>
> All good, but there's some question about the color palette in use. (There 
> are several shades of green, we need to adjust some, and it appears the 
> Official™ shade isn't actually in use, so...) 
> Having a specialist designer on board would enable that discussion to go 
> much more quickly and securely down the Happy Path there, without the risk 
> of death-by-a-thousand-cuts to the whole aesthetic. 
> This would be a big value-add to have available, without I think being a 
> big time commitment for the folks involved. 
>
> Kind Regards,
>
> Carlton
>
>
> On Monday, 2 November 2020 at 12:51:23 UTC+1 James Bennett wrote:
>
>> Taking this as a question posed under the DEP 10 voting process of 
>> whether or not to accept DEP 11:
>>
>> I vote +1.
>>
>> I think the basic idea is good; there are a couple things worth 
>> clarifying, mostly in terms of oversight, but that can be addressed in 
>> later edits.
>>
>> And by "oversight" I mean a clear statement of how members of the team 
>> are to be chosen, who will do the choosing, and whether the ultimate 
>> responsibility lies with the Django Technical Board or with the DSF Board 
>> of Directors. Since the scope of the DEP includes things that the Technical 
>> Board lacks authority over, it may need to be the DSF Board or a mix of 
>> both; also, the DSF Board would need to formally accept that responsibility.
>>
>>
>> On Thu, Oct 29, 2020 at 4:01 AM Carlton Gibson  
>> wrote:
>>
>>> Hello all. 
>>>
>>> Can I ask the Technical Board for Review and Resolution 
>>> <https://github.com/django/deps/blob/master/final/0001-dep-process.rst#review--resolution>
>>>  
>>> on DEP 11 please? 
>>>
>>> https://github.com/django/deps/pull/69/
>>>
>>> (Please let me know if I've done that wrong.) 
>>>
>>> Kind regards, 
>>> Carlton
>>>
>>> On Thursday, 22 October 2020 at 10:43:03 UTC+2 Carlton Gibson wrote:
>>>
>>>> Hi all. 
>>>>
>>>> The DEP for creating an accessibility team is looking good. 
>>>> https://github.com/django/deps/pull/69
>>>>
>>>> I'm going to ask for formal consideration shortly. 
>>>> If you have an interest/a moment, over the weekend say, to give it a 
>>>> glance before that, then any comments will be gratefully received I'm 
>>>> sure. 
>>>>
>>>> Thanks. 
>>>>
>>>> Kind Regards,
>>>>
>>>> Carlton
>>>>
>>>>
>>>> On Wednesday, 16 September 2020 at 00:17:35 UTC+2 Thibaud Colas wrote:
>>>>
>>>>> I’d love to! But worth bearing in mind that I haven’t done any

Re: Default change password UX: area for improvements

[Thibaud Colas]

Good idea! I think it’s worth mentioning as well the current link’s styles 
wouldn’t pass accessibility guidelines, as there isn’t enough contrast 
between the link color and surrounding text color, and the choice of words 
doesn’t make the link very identifiable either.

This would need to remain an `` tag so it has the best possible 
semantics – I think styling this like a button would make this as easily 
identifiable as possible, but from the perspective of the accessibility 
issues it would be enough to add an underline to the link style and make 
sure the link text makes sense without context.

Cheers,

Thibaud

On Monday, 7 June 2021 at 22:32:36 UTC+1 in...@markusholtermann.eu wrote:

> Hi Federico,
>
> this is a good idea. Could you check if there's a ticket about this on 
> https://code.djangoproject.com/ already, and if not, possibly open one. 
> That would be much appreciated. Thank you!
>
> Cheers,
>
> Markus
>
> On Mon, Jun 7, 2021, at 11:12 PM, Federico Capoano wrote:
> > Hey everyone,
> > 
> > Given the following text in the user change page:
> > 
> > *Raw passwords are not stored, so there is no way to see this user’s 
> > password, but you can change the password using this form.*
> > *
> > *
> > Linking the change user password form using the word "this form" is on 
> > the same level of links with "click here", which is notoriously bad UX 
> > and I believe the django community is made of a lot of experts so there 
> > shouldn't be the need to explain this here.
> > 
> > However, we can do better than just changing the link form, wouldn't it 
> > be possible to add a link styled as a button?
> > 
> > Eg:
> > 
> > Raw passwords are not stored, so there is no way to see this user’s 
> > password, but the password can be changed.
> > 
> > *Change the password*
> > 
> > BTW, this idea came from this issue: 
> > https://github.com/openwisp/openwisp-radius/issues/265.
> > We can easily fix it in our django app but I thought it may be good to 
> > raise this here so we may fix it at the root instead.
> > 
> > Best regards
> > Federico Capoano
> > 
> > -- 
> > You received this message because you are subscribed to the Google 
> > Groups "Django developers (Contributions to Django itself)" group.
> > To unsubscribe from this group and stop receiving emails from it, send 
> > an email to django-develop...@googlegroups.com.
> > To view this discussion on the web visit 
> > 
> https://groups.google.com/d/msgid/django-developers/CAERYH6VUm-bRsHkY_1LX9TwpJvMW%2B-Eyqf0Uye6FL%2B_Pb_%3D%2BQw%40mail.gmail.com
>  
> <
> https://groups.google.com/d/msgid/django-developers/CAERYH6VUm-bRsHkY_1LX9TwpJvMW%2B-Eyqf0Uye6FL%2B_Pb_%3D%2BQw%40mail.gmail.com?utm_medium=email_source=footer
> >.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/9410e840-37b2-47f1-b0b1-d89732c7463fn%40googlegroups.com.

Accessibility standards & contribution guidelines for Django

[Thibaud Colas]

Hi django-developers,

This is a long-overdue follow up to DEP 11 
 
and the creation of Django’s accessibility team. As part of implementing 
what this DEP outlines, we need to discuss what accessibility standards 
should apply to Django, among other things. In my opinion this is both a 
matter of deciding what pre-existing standards / guidelines would be 
relevant in theory, but also how to make sure whichever ones we choose are 
achievable to follow in practice. We need to find some consensus on what 
Django as a project should aim for, so our team and all contributors can 
take it into consideration, and in particular so we can document what we 
want to commit to as a reference for accessibility work.

Here are accessibility team responsibilities 

 
I would like to bring up for discussion in particular:

   - *Deciding on any relevant accessibility guidelines to follow, such as 
   WCAG, and at which conformance level.*
   - *Coordinating regular manual accessibility audits on all relevant 
   projects.*
   - *Writing and maintaining documentation relating to accessibility, such 
   as a statement of commitment to accessibility issues, and contribution 
   guidelines.*

Now I’ll try to outline what I’d suggest for each area, which people here 
are very welcome to disagree with as relevant. 

Accessibility guidelines

In my opinion, the most important standard for *_sites built with Django_* 
is WCAG 2.1, AA level. Anything resulting in AA level issues should be 
considered as a bug. Wherever possible, we should also strive to not get in 
the way of sites built with Django aiming for AAA level compliance.

For the Django admin, I would recommend the same target of WCAG 2.1 AA 
level as a baseline, aiming for AAA wherever possible. For example, the 
link text issue discussed in Default change password UX: area for 
improvements 
 is 
a case where I’d expect us to want to follow WCAG SC 2.4.9: Link Purpose 
(Link Only) 
, 
even though it’s level AAA.

This distinction between "sites built with Django" and the "Django admin" 
highlights an important point, which is that for lots of sites the Django 
admin would be what accessibility standards call an authoring tool. There 
is a separate standard for authoring tools that builds upon WCAG 2.1: ATAG 
2.0. I think we should also explicitly aim for compliance with ATAG 2.0 
wherever possible, as it has a lot of useful guidelines we could follow for 
the Django admin. For Django itself, there might be very little to do to 
implement those guidelines, but for the wider ecosystem of CMS-like 
features in Django it would make a clear difference if Django was clearly 
defined as an authoring tool. WCAG itself is a very thin baseline as 
standards go, so anything that goes beyond it is well worth considering in 
my opinion.

For everything else within the Django ecosystem – the documentation, the 
djangoproject.com website, the bug tracker, IRC, plain-text documentation, 
etc. – we should follow the exact same standard. I would also really like 
to see the same standard being explicitly recommended for consideration for 
third-party Django projects (similarly to Django projects wanting to 
provide the same level of browser and language support as Django itself, I 
imagine). This probably warrants a separate conversation but I would also 
recommend the Django Software Foundation explicitly mandating the same 
standard for any project or event it endorses.

It’s worth mentioning as well that the next version of WCAG, WCAG 2.2, is 
due to be released by the end of 2021. I’d recommend we don’t aim for 
support with WCAG 2.2 right now, but do so as soon as it’s released. In the 
meantime, we should also consider any WCAG 2.2-only guideline wherever 
reasonable (for example in audits, design of new features, etc.).

Contribution guidelines

Aiming for compliance with specific standards is good, but we shouldn’t 
expect Django contributors to be familiar with WCAG, or any other standard. 
I think it’s important we update the contribution guidelines to propose 
practical support targets:


   - *Which automated or semi-automated testing tools to use when testing 
   changes to Django*. My go-to is anything Axe 
-based, 
   as it’s ubiquitous, and has very few false positives. In particular with 
   the Accessibility Insights  browser 
   extension.
   - *Which assistive technologies should we explicitly strive to test 
   Django with, so contributors have clear guidance on how to test their 
   changes*. For example here are the testing guidelines for public sector 
   sites in the UK 
   

Re: Accessibility standards & contribution guidelines for Django

[Thibaud Colas]

Thank you all for the feedback :) I have a feeling it might indeed be 
easier for me to propose this for review in the form of a pull request to 
the Django docs, as I have quite a clear idea of what I’d propose at a high 
level.

On testing tools, yes, both Pa11y and Lighthouse would be worth 
considering. They both use Axe to do the actual checks, which means results 
will be largely comparable between Lighthouse, Pa11y, and Accessibility 
Insights. I’ve set up automated tests for the Django admin based on Pa11y + 
Lighthouse, which you can see here: django_admin_tests 
<https://github.com/thibaudcolas/django_admin_tests>. My preference as "the 
one tool" to recommend still is Accessibility Insights, as it contains a 
good mixture of automated and semi-automated checks, as well as a very 
thorough wizard to guide people through manual checks.

> I wanted to check the issue on password UX but maybe I can help on others 
things related to this before. Tell me what do you think.

There’s quite a lot of ground to cover, so any and all help is welcome :) 
If you’re interested in UX work generally – once we start properly auditing 
the Django admin, reporting issues will be straightforward enough, but 
proposing solutions will be much harder. Anyone with a good mix of Django 
and UX expertise will be in a great position to contribute. For example, 
last week I audited django-postgres-metrics 
<https://www.youtube.com/watch?v=8pegTdRaUDg> and found a few issues 
relating to table sorting. Fixing those issues could be an opportunity to 
generally improve the table sorting UX for all.

> I am not completely sure about the definition of an "authoring tool",
but it might make sense to consider django as a whole as such an
authoring tool, not just the Django admin. ATAG A. (Make the authoring
tool user interface accessible) would then only apply to Django admin,
but ATAG B. (Support the production of accessible content) would apply
to everything.

Indeed! There are a few things that likely couldn’t apply (Guideline B.3.2: 
Assist authors in repairing accessibility problems 
<https://www.w3.org/TR/2015/NOTE-IMPLEMENTING-ATAG20-20150924/#gl_b32>) but 
they feel like they might be the exception rather than the rule. It’s 
certainly a helpful lens to consider accessibility improvements through.

Best regards,

Thibaud

On Tuesday, 15 June 2021 at 18:19:41 UTC+1 Tobias Bengfort wrote:

> Hi Thibaud,
>
> thanks for the follow up. +1 on basically everything you wrote!
>
> On 15/06/2021 02.59, Thibaud Colas wrote:
> > This distinction between "sites built with Django" and the "Django 
> > admin" highlights an important point, which is that for lots of sites 
> > the Django admin would be what accessibility standards call an authoring 
> > tool. There is a separate standard for authoring tools that builds upon 
> > WCAG 2.1: ATAG 2.0. I think we should also explicitly aim for compliance 
> > with ATAG 2.0 wherever possible, as it has a lot of useful guidelines we 
> > could follow for the Django admin. For Django itself, there might be 
> > very little to do to implement those guidelines, but for the wider 
> > ecosystem of CMS-like features in Django it would make a clear 
> > difference if Django was clearly defined as an authoring tool. WCAG 
> > itself is a very thin baseline as standards go, so anything that goes 
> > beyond it is well worth considering in my opinion.
>
> I am not completely sure about the definition of an "authoring tool", 
> but it might make sense to consider django as a whole as such an 
> authoring tool, not just the Django admin. ATAG A. (Make the authoring 
> tool user interface accessible) would then only apply to Django admin, 
> but ATAG B. (Support the production of accessible content) would apply 
> to everything.
>
> > * *Which automated or semi-automated testing tools to use when testing
> > changes to Django*. My go-to is anything Axe
> > <https://www.deque.com/axe/>-based, as it’s ubiquitous, and has very
> > few false positives. In particular with the Accessibility Insights
> > <https://accessibilityinsights.io/> browser extension.
>
> AFAIK the accessibility checker in chrome's lighthouse is also based on 
> Axe. As it is already built into a very popular browser this might lower 
> the threshold for testing even further.
>
> tobias
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/80cffd96-1550-4c51-9ca7-465449427b39n%40googlegroups.com.

Re: Changing widget rendering templates

[Thibaud Colas]

Hi all,

I wanted to mention a couple more things that might help in the decision:


   - There is no direct accessibility issue *for end users* from `as_p` 
   that I know of. The only issue is its propensity to making people create 
   forms with invalid HTML (see #31189 
   ), which is problematic 
   when running HTML validation, and is a failure of WCAG 2.1 level A SC 
   4.1.1 Parsing  
(this 
   standard being the most likely target for Django, although there is no 
   official target as of now).
   - I’ve just opened two tickets that, if confirmed, would require 
   additional changes to the widgets’ rendering to fix: #32819 
   , #32820 
   .

I imagine we want to release changes to forms’ rendering as infrequently as 
possible. If we considered grouping those changes all in the same release, 
it could be worthwhile for me to further review forms and fields for any 
further issues there might be, so they can be fixed at the same time. One 
problem I’m facing with this and similar audits is that I almost never use 
Django’s default markup myself, so it would be nice for others to look at 
the form I’m using for testing (code 

, rendering ) 
and confirm it’s suitable. Or provide alternative forms you might already 
be aware of, set up differently or showcasing more advanced widget 
configurations.

Those additional tickets reflect the extent of my audit progress to date. 
One thing I’m considering but am uncertain of is whether non-field errors 
would also need ARIA markup, to be more identifiable as errors, and-or 
programmatically associated with the form. I still need to research this, 
both according to specs, and with actual support from screen readers.

Kind regards,

Thibaud

On Saturday, 5 June 2021 at 09:31:54 UTC+1 Adam Johnson wrote:

> I think a breaking change for the widget HTML is fine too, if it improves 
> everyone’s apps. Perhaps documenting in the release notes how to undo it 
> (eg copy this template file into your project, reconfigure the widget to 
> use the template like so) will make it easier for folks with incompatible 
> CSS to upgrade.
>
> On Sat, 5 Jun 2021 at 08:45, Carlton Gibson  wrote:
>
>> Hi David. 
>>
>> Thanks for this. Sorry for the slow pick-up: DjangoCon this week. :)
>>
>> I'd say option 1: It's an accessibility change and we should just opt 
>> people into that. IIRC there are some small improvements to the current 
>> HTML (aria roles and such) that would improve accessibility even if not 
>> perfectly. We should add those. (Folks can revert to the old templates if 
>> they must, assuming we note the changes.)
>>
>> With the template based rendering in place, I'd think (though) we could 
>> eventually move away from `as_p`  
>> Rather you'd set the (base) `template_name` for the form, or override 
>> `django/forms/default.html`, which in the PR proxies to `table.html` to 
>> maintain the current behaviour, and then rely on `__str__()`, i.e. you'd do 
>> `{{ form }}`. 
>>
>> If we keep `table.html`, `ul.html` and `p.html`, folks who are using `{{ 
>> form }}` now can add the `as_*` as needed to keep the current output 
>> (modulo the aria type changes). 
>>
>> We should then be free to introduce a better `default.html` that 
>> addresses the accessibility issues more comprehensively. I think there's no 
>> problem heading towards this. 
>>
>> I think we do have to leave that fallback though: I'd guess the number 
>> of projects using `as_p`  somewhere is legion; just changing the HTML 
>> would be a pretty big break without a fallback... 樂 Whether it's worth the 
>> disruption to formally deprecate and remove these methods I don't know... 
>> We could add a warning to as_p  to say "This method 
>> has accessibility issues" if we wanted to steer people away — There's 
>> probably value if having two or three different examples of how you could 
>> render a form, especially if we can solve the worst of the accessibility 
>> concerns.
>>
>> Kind Regards,
>>
>> Carlton
>>
>>
>> On Friday, 4 June 2021 at 08:56:12 UTC+2 smi...@gmail.com wrote:
>>
>>> Hey all,
>>>
>>> I've been looking at the couple of tickets open to improve accessibility 
>>> of the forms and checkbox/radio widgets. [1][2]
>>>
>>> While changing the layout is _fairly_ straight forward I'm unsure how to 
>>> transition to the new way. I'm focusing this change in changing the widget 
>>> templates until the patch for template based rendering of forms is merged.
>>>
>>> I think the options are:
>>>
>>> 1) Just make the change and have a breaking change. 
>>>
>>> 2) Introduce the new template and deprecate use of the old 

Re: Revisiting multiline template tags in Django Templates (again)

[Thibaud Colas]

Just wanted to follow up that I got to discuss this in person with Carlton 
Gibson at the DjangoCon Europe sprints in Porto, who provisionally offered 
to act as a shepherd for this proposed DEP. This is on the condition that I 
find an implementation team as well.

On Saturday, 24 September 2022 at 08:37:52 UTC+1 Thibaud Colas wrote:

>  Hi django-developers, I would like to revisit a very old feature 
> request: ticket #8652 Multiline tags and tag escape tags 
> <https://code.djangoproject.com/ticket/8652>, proposed DEP Multiline 
> Template Tags <https://github.com/django/deps/pull/3>, and maling list 
> thread Revisiting multiline tags 
> <https://groups.google.com/g/django-developers/c/wRKgnMIhl6g/m/hMRHPIz4CgAJ>
> .
>
> There have been a lot of cases made against and for multiline template 
> tags across many threads. I’m raising this on the mailing list not 
> necessarily to revisit those arguments but to ask:
>
>1. Is a DEP indeed the best way forward for this at this point in 
>time? If so I will volunteer to author it (co-authors welcome!).
>2. The last DEP got blocked due to the lack of an implementation team 
>and shepherd. If we made a new (proposed) DEP – is anyone here interested 
>in helping in either positions?
>
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/ddc74d02-63df-479a-968c-2ee44b696bd2n%40googlegroups.com.

Permissions don't get translated in admin interface

[Thibaud Colas]

 there have been a lot of discussions and tickets opened on permissions 
translations in the past. I’m not sure what the etiquette here is, hence 
why I’m starting a new conversation.

I would like to see #1688 Permissions don't get translated in admin 
interface  reconsidered, as to 
me it seems like a clear bug, which affects a lot of users. Though not many 
people might be managing permissions regularly, when you do, it’s very 
jarring that the text is in the wrong language.

I’m not sure what Django’s stance is on supporting non-english users 
generally, but based on our diversity statement I feel like "100% of the 
admin UI translated" is an important goal – and looking at Transifex 
, there are a lot of people 
putting in a lot of effort to get it there. If this is a wontfix because 
the store-label-in-DB approach is effectively impossible to make work, then 
I think this would be worth clearing documenting on the Localizing Django 
 
page so translators know what to expect. Ideally also mention elsewhere in 
a place visible to end users.

---

>From a technical perspective, this is far from my area of expertise but as 
I understand there are clear solutions – one that’s "quick and dirty" would 
be to hard-code a list of gettext_lazy calls with the same labels as stored 
in the DB for the purpose of collecting the labels for PO files, and then 
we could use {% translate %} over the DB-provided values anyway. No change 
to the DB needed. I count 8 Django-provided models in my demo site (might 
be missing others), each has 4 Django-provided permissions, so that’s 32 
strings to hard-code. Feels doable!


-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/8e14c59f-3331-401a-85a1-cbf27d49fe65n%40googlegroups.com.

Revisiting multiline template tags in Django Templates (again)

[Thibaud Colas]

 Hi django-developers, I would like to revisit a very old feature 
request: ticket #8652 Multiline tags and tag escape tags 
, proposed DEP Multiline 
Template Tags , and maling list 
thread Revisiting multiline tags 

.

There have been a lot of cases made against and for multiline template tags 
across many threads. I’m raising this on the mailing list not necessarily 
to revisit those arguments but to ask:

   1. Is a DEP indeed the best way forward for this at this point in time? 
   If so I will volunteer to author it (co-authors welcome!).
   2. The last DEP got blocked due to the lack of an implementation team 
   and shepherd. If we made a new (proposed) DEP – is anyone here interested 
   in helping in either positions?


-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/4f3d0e3b-1fd5-4189-8014-c2aaba157b48n%40googlegroups.com.

Re: Permissions don't get translated in admin interface

[Thibaud Colas]

I worked on a potential fix for this yesterday at the Django London’s hack 
day with Nick (hi Nick if you’re reading this!). 

   - Here is where translation names get 
   created: 
https://github.com/django/django/blob/main/django/contrib/auth/management/__init__.py#L31
   - And where the strings are generated for 
   display: 
https://github.com/django/django/blob/main/django/contrib/auth/models.py#L78
   - As well 
   as: 
https://github.com/django/django/blob/main/django/contrib/contenttypes/models.py#L150

And here is a draft PR that makes those labels fully translate-able at 
least for the default 
permissions: https://github.com/thibaudcolas/django/pull/1

It seems to work well. As far as I could see, there’s no reason for at 
least the app name to be displayed in english (just need to switch from 
app_label to verbose_name).
On Sunday, 25 September 2022 at 14:02:33 UTC+1 Thibaud Colas wrote:

> Thank you all for your suggestions so far :) Just to give a little bit 
> more background – aside from ticket #1688 Permissions don't get 
> translated in admin interface <https://code.djangoproject.com/ticket/1688>, 
> this had also been discussed in Translation of group permissions 
> <https://groups.google.com/g/django-developers/c/w93rJrPTPy0/m/1XfgIF28BgAJ> 
> on 
> the mailing list (though it’s not just for groups).
>
> To clarify what I’m after – in my opinion this needs to be treated as a 
> bug to fix in Django itself – at least for translations of built-in 
> permissions. Having a way to do this for custom ones would be nice too (see 
> for example Wagtail issue #5341 
> <https://github.com/wagtail/wagtail/issues/5341>). So devising how to fix 
> this would be nice, but right now this is officially a "wontfix" so this 
> would need to be addressed first.
>
> For reference, here is a screenshot of the current state, in Arabic 
> (right-to-left language so the UI is partly mirrored):
>
> [image: translations-current-state.png]
>
> Translation names aren’t translated, while their model names are 
> translated, and the app name isn’t translated ("auth" vs. app label 
> "المصادقة والتفويض" in the sidebar).
> On Sunday, 25 September 2022 at 12:12:21 UTC+1 ramez...@gmail.com wrote:
>
>> Hello 
>>
>> it's for this reason, i created this package 
>> https://github.com/RamezIssac/django-tabular-permissions
>> It displays the permissions in a table that is easily translated , and 
>> easier to work with
>>
>> Aside from a 3rd party app, a workaround (like the one suggested above) 
>> will be the way to go.
>> For Django core, it think its very hard to do it as one can also have 
>> more than one non English of languages supported .. which permission 
>> language will be recorded in the database then ?
>>
>> Screen shot for tabular permissions
>> [image: tabular_permisions.png]
>>
>> On Sunday, September 25, 2022 at 3:07:27 AM UTC+2 baido...@gmail.com 
>> wrote:
>>
>>> Thanks
>>>
>>> On Sat, Sep 24, 2022, 22:28 Danilov Maxim  wrote:
>>>
>>>> Hi, Tribaud.
>>>>
>>>>  
>>>>
>>>> In your case you can override Permission admin to show translated names 
>>>> of permissions and for widgets you can override modelchoiceiterator
>>>>
>>>> The name of permission you can translate like model.verbose_name + 
>>>> gettext( ‘can’) + gettext(view/change/delete) and it should be translated.
>>>>
>>>> With custom translation is a little bit  more work, but it also works. 
>>>>
>>>> I am not sure, that if override of __str__ helps, but it also possible.
>>>>
>>>>  
>>>>
>>>>  
>>>>
>>>> By the way - My solution DJANGO-TOF 2.version solves you ask without 
>>>> any changes in code.
>>>>
>>>> I‘ve presented it on last Django con 2022
>>>>
>>>> We works with permissions and also custom permissions already long time 
>>>> in Multilanguage Project and I don’t see any problem with that.
>>>>
>>>>  
>>>>
>>>>  
>>>>
>>>> Mit freundlichen Grüßen,
>>>>
>>>> DI Mag. Maxim Danilov
>>>>
>>>>  
>>>>
>>>> +43(681)207 447 76
>>>>
>>>> ma...@wpsoft.at
>>>>
>>>>  
>>>>
>>>> *From:* django-d...@googlegroups.com [mailto:
>>>> django-d...@googlegroups.com] *On Behalf Of *Thibaud Colas
>>>> *Sent:* Saturday, September 24, 2022 9:25 AM
>>

Re: Permissions don't get translated in admin interface

[Thibaud Colas]

Ah-ha! Correct :) That’s great. So as of that commit, it’s just the 
permission names that aren’t translated. Here’s a screenshot of the current 
state:

[image: permission-names-django-Django-5.0.dev20230602105440.png]

I’ve updated my POC accordingly 
(https://github.com/thibaudcolas/django/pull/1), the implementation is 
still hacky but now only requires changes in the Permission model.

On Friday, 2 June 2023 at 19:40:04 UTC+1 Mariusz Felisiak wrote:

> Is it not partly fixed by a52bdea5a27ba44b13eda93642231c65c581e083 
> 
> ?
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/de16efdf-f825-41cc-bf6a-9a820f9db2efn%40googlegroups.com.

Re: Permissions don't get translated in admin interface

[Thibaud Colas]

 without further input, I’m not quite sure what to do with this. We need 
this ticket re-opened so anyone actually considers working on a fix for 
this. For reference, the initial reason for closing this bug report was:

> The permissions are stored in the database and don't get translated.

To me at least this is a poor reason. First off this is still a clear bug 
from the perspective of people who expect the admin to be in the language 
of their choosing. Second, there are clear ways to improve upon this even 
without significantly re-engineering how permission names are generated 
(see message above – and my proof of concept 
<https://github.com/thibaudcolas/django/pull/1>).

Any takers? Should I post this elsewhere?
On Friday, 14 October 2022 at 05:45:34 UTC+1 Thibaud Colas wrote:

> I worked on a potential fix for this yesterday at the Django London’s hack 
> day with Nick (hi Nick if you’re reading this!). 
>
>- Here is where translation names get created: 
>
> https://github.com/django/django/blob/main/django/contrib/auth/management/__init__.py#L31
>- And where the strings are generated for display: 
>
> https://github.com/django/django/blob/main/django/contrib/auth/models.py#L78
>- As well as: 
>
> https://github.com/django/django/blob/main/django/contrib/contenttypes/models.py#L150
>
> And here is a draft PR that makes those labels fully translate-able at 
> least for the default permissions: 
> https://github.com/thibaudcolas/django/pull/1
>
> It seems to work well. As far as I could see, there’s no reason for at 
> least the app name to be displayed in english (just need to switch from 
> app_label to verbose_name).
> On Sunday, 25 September 2022 at 14:02:33 UTC+1 Thibaud Colas wrote:
>
>> Thank you all for your suggestions so far :) Just to give a little bit 
>> more background – aside from ticket #1688 Permissions don't get 
>> translated in admin interface 
>> <https://code.djangoproject.com/ticket/1688>, this had also been 
>> discussed in Translation of group permissions 
>> <https://groups.google.com/g/django-developers/c/w93rJrPTPy0/m/1XfgIF28BgAJ> 
>> on 
>> the mailing list (though it’s not just for groups).
>>
>> To clarify what I’m after – in my opinion this needs to be treated as a 
>> bug to fix in Django itself – at least for translations of built-in 
>> permissions. Having a way to do this for custom ones would be nice too (see 
>> for example Wagtail issue #5341 
>> <https://github.com/wagtail/wagtail/issues/5341>). So devising how to 
>> fix this would be nice, but right now this is officially a "wontfix" so 
>> this would need to be addressed first.
>>
>> For reference, here is a screenshot of the current state, in Arabic 
>> (right-to-left language so the UI is partly mirrored):
>>
>> [image: translations-current-state.png]
>>
>> Translation names aren’t translated, while their model names are 
>> translated, and the app name isn’t translated ("auth" vs. app label 
>> "المصادقة والتفويض" in the sidebar).
>> On Sunday, 25 September 2022 at 12:12:21 UTC+1 ramez...@gmail.com wrote:
>>
>>> Hello 
>>>
>>> it's for this reason, i created this package 
>>> https://github.com/RamezIssac/django-tabular-permissions
>>> It displays the permissions in a table that is easily translated , and 
>>> easier to work with
>>>
>>> Aside from a 3rd party app, a workaround (like the one suggested above) 
>>> will be the way to go.
>>> For Django core, it think its very hard to do it as one can also have 
>>> more than one non English of languages supported .. which permission 
>>> language will be recorded in the database then ?
>>>
>>> Screen shot for tabular permissions
>>> [image: tabular_permisions.png]
>>>
>>> On Sunday, September 25, 2022 at 3:07:27 AM UTC+2 baido...@gmail.com 
>>> wrote:
>>>
>>>> Thanks
>>>>
>>>> On Sat, Sep 24, 2022, 22:28 Danilov Maxim  wrote:
>>>>
>>>>> Hi, Tribaud.
>>>>>
>>>>>  
>>>>>
>>>>> In your case you can override Permission admin to show translated 
>>>>> names of permissions and for widgets you can override modelchoiceiterator
>>>>>
>>>>> The name of permission you can translate like model.verbose_name + 
>>>>> gettext( ‘can’) + gettext(view/change/delete) and it should be translated.
>>>>>
>>>>> With custom translation is a little bit  more work, but it also works. 
>

Re: Permissions don't get translated in admin interface

[Thibaud Colas]

As suggested by @nessita on Discord, I’ve taken this to the Django Forum in 
Django 
Internals: 
https://forum.djangoproject.com/t/permissions-dont-get-translated-in-admin-interface/21324.

Let’s try to keep the discussion going over there!

On Friday, 2 June 2023 at 20:58:50 UTC+1 Thibaud Colas wrote:

> Ah-ha! Correct :) That’s great. So as of that commit, it’s just the 
> permission names that aren’t translated. Here’s a screenshot of the current 
> state:
>
> [image: permission-names-django-Django-5.0.dev20230602105440.png]
>
> I’ve updated my POC accordingly (
> https://github.com/thibaudcolas/django/pull/1), the implementation is 
> still hacky but now only requires changes in the Permission model.
>
> On Friday, 2 June 2023 at 19:40:04 UTC+1 Mariusz Felisiak wrote:
>
>> Is it not partly fixed by a52bdea5a27ba44b13eda93642231c65c581e083 
>> <https://github.com/django/django/commit/a52bdea5a27ba44b13eda93642231c65c581e083>
>> ?
>>
>>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/4d06cb27-ef19-4cd6-98be-6cf1d68d20ffn%40googlegroups.com.

Re: Django t-shirt

[Thibaud Colas]

Hi Fabien, for what it’s worth Django also has merch with FreeWear, who are 
based in Spain: https://www.freewear.org/Django

Cheers,

Thibaud

On Monday, 16 January 2023 at 13:26:25 UTC Fabien Schwob wrote:

> Hello,
>
> It would be awesome to also have a Threadless alternative for Europe, to 
> avoid huge delivery costs and customs fees.
>
> Best regards,
>
> Dim 15 janv 2023, à 09:03, 'Adam Johnson' via Django developers  
> (Contributions to Django itself) a écrit :
>
> There is a Django Threadless store where you can buy T-Shirts and other 
> merchandise, which all supports the DSF: https://django.threadless.com/
>
> It’s linked from the fundraising page: 
> https://www.djangoproject.com/fundraising/
>
> I have a Django phone case from there!
>
> On Fri, Jan 13, 2023 at 11:44 AM Stephen Wolff  
> wrote:
>
> Hi there,
>
> A few Django versions ago (1.7 and maybe 1.8?!), t-shirts were produced 
> and sold (i guess for fundraising purposes?).
>
> Just wondering given the forthcoming LTS is 4.2, which has similarities to 
> Douglas Adams's answer to the life, universe and everything, whether a new 
> t-shirt could be produced?
>
> Yours hopefully,
>
> Stephen
>
>
> -- 
> You received this message because you are subscribed to the Google Groups 
> "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to django-develop...@googlegroups.com.
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/django-developers/7570a944-3822-4493-acf0-4510c24e7b8bn%40googlegroups.com
>  
> 
> .
>
>
> -- 
> You received this message because you are subscribed to the Google Groups 
> "Django developers (Contributions to Django itself)" group.
> To unsubscribe from this group and stop receiving emails from it, send an 
> email to django-develop...@googlegroups.com.
>
> To view this discussion on the web visit 
> https://groups.google.com/d/msgid/django-developers/CAMyDDM2jQx2RTyDktvi%2BTCMa%3D4PR43SXPpwxv7V9A8bL-z-hEA%40mail.gmail.com
>  
> 
> .
>
>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/a75c0e16-1670-464d-9d6e-20835ba22df8n%40googlegroups.com.

Re: Model icons

[Thibaud Colas]

Hi all, I see Wagtail has been mentioned, we actually shipped a lot of 
improvements to our icons support in our last release, thought I’d share a 
few details in case it helps in considering this for Django.

Here is Wagtail’s documentation for custom 
icons: https://docs.wagtail.org/en/stable/advanced_topics/icons.html. The 
TL;DR; is:

   - Icons are SVG files, registered in the CMS with a unique identifier 
   (for example "fa-user-solid")
   - This makes it possible to create "icon pack" packages 
   ("django-fontawesome", "django-myiconset"), which register large amounts of 
   icons. And also allows for specific projects to register their own custom 
   icon(s).
   - In different parts of the code (Wagtail’s ModelAdmin equivalents), we 
   allow providing an icon identifier.
   - We have a set of built-in icons, most from FontAwesome, some custom.
   - icons are then loaded as an inline SVG "sprite" (SVG symbol elements).


As an aside, the Django admin’s current iconography is in a dire need of 
being rebuilt. Its implementation with `img` elements and background images 
is really less than ideal for accessibility, because it makes it really 
hard to style icons according to different needs (light theme, dark theme, 
high contrast mode) and UI states (error, focus, etc).

Cheers,

Thibaud

On Friday, 3 March 2023 at 15:08:24 UTC Bogdan Barna wrote:

>
> Hello all,
>
> I've joined this emailing list just to support the fellow users, of not 
> adding this (especially on models.Model) as per their points made.
>
> Thanks,
> Bogdan
>
> On Thursday, February 23, 2023 at 5:54:44 PM UTC+2 Jacob Rief wrote:
>
>> On Thu, Feb 23, 2023 at 7:38 AM Brice Parent  wrote:
>>
>>> Hello!
>>>
>>> Really useful idea, I think! 2 points about it: 
>>>
>>> 1. Syntax
>>>
>>> I would also remove the html from the models, but probably in this way:
>>> class Hammer(models.Model):
>>> ...
>>>
>>> Meta:
>>> icon = ModelIcon("")
>>>
>>>
>>> There would be something like 
>>>
>>> ModelIcon.as_html(self, model_name:str) -> str:
>>> """returns whatever html should be used in the admin"""
>>>
>>>
>>> or a ModelIcon.set_text(self, text: str) and we'd use a simple 
>>> str(model_icon) in the templates.
>>>
>>> In my opinion, Django models shall not have to specify parts of their 
>> representation layer, such as icons.
>> This shall be left exclusively to the view layer: The ModelAdmin is such 
>> a candidate.
>>
>> That way, it could be extended easily in a 
>>> FontAwesomeModelIcon("fa-hammer") and a BootstrapModelIcon("bi-hammer") for 
>>> example, and maybe get whatever extra arguments they may need, like 
>>> FontAwesomeModelIcon("fa-hammer", thickness="solid").
>>>
>>> I don't like the idea that Django becomes dependent on any 
>> UTF-8-Symbol/Dingbats/Emojis/Glyphicon/Font-Awesome/Bootstrap/Remix/etc-Iconset.
>> Some Models might have a purpose which can not be mapped to any of those 
>> icons and need to be custom designed.
>>  
>>
>>> 2. Make it more widely useful
>>> I like the fact that it's in the model itself and not in the modeladmin, 
>>> as it allows to use it elsewhere, like in the __str__ to quickly add this 
>>> visual indication of the class. Boostrap and co would have to provide a 
>>> non-html version of the icon or return an empty string though.
>>>
>>> That's a violation of the well established MVC pattern of keeping the 
>> visual part in the view, and the "business model" within the model.
>>
>> Just my 2 cents
>> – Jacob
>>
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/7d9fa096-8105-47ab-a778-537294ddccf9n%40googlegroups.com.

Re: Transition Docs to Inline

[Thibaud Colas]

Hi Moshe,

Just so you know there are a lot more discussions about Django these days 
on the Django Forum  than this mailing 
list. There are also no such things as Django lords or a governing board :) 
The project is consensus-driven, so doesn’t require any specific seal of 
approval.

As a Django beginner I’d really like better support for IDEs with those 
"hover" features you mentioned – and I don’t see why we’d have to move the 
docs inline to do that. Why not add docstrings where they’re missing, in 
addition to the docs as they stand currently? Django is a big enough 
project that there’s room to provide docs in different ways for different 
needs, and it doesn’t change often enough that keeping docs in sync would 
be an issue. According to the Django Developers Survey in 2022 
, 80% of Django 
devs use an IDE that offers this "inline docs on hover" developer 
experience nicety.

Django does have plenty of docstrings like this already, so perhaps we can 
add concise ones where there’s none currently in the public API, rather 
than having a big documentation refactoring project. Something like this – 
would be a quick win to add a one-liner for ModelForm:

[image: modelform hover screenshot.png]

Cheers,

Thibaud




On Thursday 11 January 2024 at 17:32:28 UTC Jörg Breitbart wrote:

> I agree that the official Python docs are well maintained and achieve a 
> tough goal - the right balance of just replaying basic interface facts 
> on one side, or being overly prosaic on the other side. Nope, they are 
> well balanced giving enough of both extremes to get you going, place 
> repo code lookup links, and examples where needed.
>
> And Python properly fills the __doc__ attribute on almost every function 
> or class, which is a big relief in interactive testing sessions to 
> quickly grasp a rarely used detail not in your muscle memory.
>
> With Django thats mostly not possible, inspecting __doc__ or using 
> help(XY) does often not reveal any useful information.
>
> > So no, I'd be a strong -1 to any recommendation suggesting that
> > docstrings be used to clutter up the code.
>
> I dont see how informative docstrings can clutter code, they are 
> visually well separated from code bodies, and most editors ven allow to 
> fold them.
>
> The bigger issue I see with docstrings is, that they sometimes end up 
> being written too machine firendly, e.g. full of restructuredText 
> formatting, which hinders human reading to some degree, esp. if you 
> never used those formats yourself before.
>

-- 
You received this message because you are subscribed to the Google Groups 
"Django developers  (Contributions to Django itself)" group.
To unsubscribe from this group and stop receiving emails from it, send an email 
to django-developers+unsubscr...@googlegroups.com.
To view this discussion on the web visit 
https://groups.google.com/d/msgid/django-developers/babf5ef5-3269-4799-bbbe-8f2599d1bd8en%40googlegroups.com.