Add a disclaimer about PDF accessibility issues in docs

[Thibaud Colas]

In the Django docs, we have ​How to create PDF files. This page needs a disclaimer explaining fundamental accessibility issues with PDFs as a format, similarly to how other areas of the docs warn users against likely performance and security issues.

For example, something along the lines of:

Warning: There are known accessibility issues with PDF files. Consider whether your use case could be achieved with a more accessible format, and make sure to provide alternatives for users.

[Natalia Bidart]

Thank you Thibaud, would you have a reference from a known site about how PDF have accessibility issues? This is news to me and I would like to know more.

[Claude Paroz]

I'm not certain that it's our responsibility to educate users about format accessibility. IMHO it's out of scope for the Django docs.

[Sarah Boyce]

The link to the ReportLab docs has it's own ​page on accessibility, quite prominently in their docs.
We could in our example do a couple of the things mentioned in that (like set a title, language and tag the "Hello world") to draw more attention to it.
We already have a note that ReportLab is not thread-safe. I think we could have a note to encourage folks to follow the accessibility guidelines

[Thibaud Colas]

I didn’t know about that page in the ReportLab docs! I’m baffled to read their tagged PDF support is ​only available for paid users, not sure what to make of that information. There’s no way a PDF with any kind of formatting in it would be considered good enough for an organization that has to follow accessibility standards.

@Natalia PDFs have accessibility issues like any other content, but they’re even more prevalent because a lot of software out there requires extra steps to produce accessible PDFs. The page shared by Sarah is a good overview of things that are often missing and can be resolved (in particular tagging). Additionally I would recommend reading:

• ​PDF/UA, the standard for PDF files’ accessibility. The first requirement "Complete tagging" is what’s only available in the paid version of ReportLab (…).
• ​Why GOV.UK content should be published in HTML and not PDF. This is a good authoritative overview of fundamental accessibility issues with the format (such as lack of responsive resizing and reflow, lack of text resizing, and color theming).

@Claude we want Django sites to be accessible.That means the framework, including docs, certainly should encourage good practices for accessibility. As is the case for security, performance, etc. A warning seems commensurate with the size of the footgun.

[Sarah Boyce]

I’m baffled to read their tagged PDF support is ​only available for paid users, not sure what to make of that information. Without tags, there’s no way a PDF with any kind of formatting in it would be considered good enough for an organization that has to follow accessibility standards.

I agree this is concerning, perhaps we should recommend ​WeasyPrint. This looks like you format it in html and you opt to convert it to a pdf (with tags)

It looks like this How-to guide was added in 2005 - do we think this guide needed at all? It uses a ​FileResponse maybe these docs are already enough?
Perhaps this how-to, which relies on an external package (possibly commercialized in the past 20 years), doesn't belong in the docs.

These are the options I see:

1. Remove this How-to
2. Move away from ReportLab
3. Add a warning to the docs
4. Do nothing

To decide a route forward, can you start a discussion on the ​forum and get more input from other folks? If there's a consensus for any of the options 1-3 please come back here, link the discussion and reopen the ticket

[Claude Paroz]

Replying to Thibaud Colas:

@Claude we want Django sites to be accessible.That means the framework, including docs, certainly should encourage good practices for accessibility. As is the case for security, performance, etc. A warning seems commensurate with the size of the footgun.

To be clear, I'm all for accessibility as far as Django itself is concerned. But for me, the choice of a PDF output is not something we should interfere with. We have to put limits in what we document, and for me, this is out of scope (but legitimate by itself, of course).

And yes, I also find ReportLab limitations saddening, but this is related to the business model of the company behind it. It's not a community-driven project.