Add links to third-party packages in documentation

[tim-schilling]

Code of Conduct

• I agree to follow Django's Code of Conduct

Feature Description

Add links to popular third-party libraries in the documentation in areas to increase visibility to the third-party ecosystem. The mentions of these libraries should be clear that they are not part of "Django" core and may go out of date.

Problem

There are too many feature ideas to be incorporated into Django core, but we also need to provide people with pathways to find these packages. By defining a pattern in the documentation that links people to a third-party package or resource to find out more about a relevant component or piece of logic, we make the ecosystem more visible.

Request or proposal

proposal

Additional Details

For quite a bit of time, Django has said no to including links to third-party packages. This started changing with the inclusion of the Django Debug Toolbar in the official tutorial. The current steering council is working on a community page that highlights various aspects of the community, as well as third-party packages, that are popular.

If we can write the references to these other packages to be clear that they are additional information, not part of django/django and suspect to change because of the nature of open-source, we may be able to get the risk of stale links to an acceptable level.

Implementation Suggestions

Some initial areas we could get started on:

• Getting started contributing could mention Djangonaut Space as a resource
• Getting started contributing could mention Jazzband and Django Commons to find other projects to work on
• The how to create custom django-admin commands could mention django-extensions
• The reference docs for storages could mention django-storages
• The production deployment and static files docs could mention whitenoise
• Authentication docs could mention django-allauth
• The permissions docs could mention django-guardian
• The settings topics could mention python-dotenv and django-environ
• Sending email could mention django-anymail
• The internationalization and localization could mention django-modeltranslation, django-modeltrans, django-rosetta

[github-actions]

Thank you tim-schilling for sharing your idea! We have a lot of them so please be patient. You can see the current queue here.

Community instructions

For commenters, please use the emoji reactions on the issue to express support, and/or concern easily. Please use the comments to ask questions or contribute knowledge about the idea. It is unhelpful to post comments of "I'd love this" or "What's the state of this?"

Reaction Guide

• 👍 This is something I would use
• 👎 This is something that would cause problems for me or Django
• 😕 I’m indifferent to this
• 🎉 This is an easy win

[LilyAcorn]

I think this is an excellent idea! I think as part of landing this, we should form a team that is responsible for managing third party package sections in the docs. I think a review once per feature release would probably make most sense.

[luzfcb]

Just remembering that https://djangopackages.org ( https://github.com/djangopackages/djangopackages ) exists and maybe it could also be referenced in docs. @jefftriplett is its current maintainer

[jefftriplett]

I'm +1 third-party packages being mentioned and we can do anything with Django Packages to make it easier to list or share packages then feel free to open a discussion or issues. I think we are a little time and scarce atm, but I am hoping we can change that over the next few months.

[mlissner]

I think I'm going to be a downer and say that I think this is a bad idea in the specifics, but a real problem in general and a good one to tackle.

The problem I see is that django often says "no" to talking officially about third party packages, but I don't think the solution is to say "yes" and to begin listing them in the documentation. The problem with that is that it takes a lot of effort, it involves picking winners and losers, and we only have so much effort to dedicate to — gestures broadly — things.

What I think might make more sense is to have a hint in the documentation that indicates, "Go find a third party package for this" or that points people to an appropriate page on djangopackages.org instead. I think it's actually useful and good for the ecosystem not to have winners and losers and to instead encourage people to research solutions via Google and other discussions. I also think it's helpful for the documentation to indicate that it's an area that Django itself has outsourced to the community — search elsewhere and you shall find answers!

For example, imagine if the Django docs say, "We recommend Django REST Framework for APIs." That would annihilate innovation in that area or at least tamp it down. A better approach would be to say, "There are a number of third-party API libraries. Please review them on DjangoPackages.org".

[carltongibson]

I think I agree with @mlissner 🤔

The docs have always been a neutral zone. Not just for the maintenance reasons, that's worth preserving. As soon as we open the door to linking to packages directly here, it becomes a what about my package?, and we're in the business of picking winners.

…annihilate innovation in that area …

Exactly.

We just added the new ecosystem page to the website:

https://www.djangoproject.com/community/ecosystem/

I'd like to see us promoting that, and evolving it beyond the first pass, and seeing how that goes before rushing to further steps.

[nessita]

Thanks for bringing this up! I'd like to share a perspective from the Fellow side of things.

I'd strongly prefer that any curated list of third-party packages live outside the Django documentation itself. I think a better place would be, for example, a flatpage or dedicated section in the website that the SC or a trusted team can control. That way, the SC has full ownership of what gets recommended and when it gets updated, without adding review or gatekeeping overhead for the Fellows.

That said, I would be in favor of linking from the Django official documentation to such a curated list in targeted and relevant places. This gives users helpful direction without turning the docs into a battleground for individual package mentions. Therefore my recommendation is to centralize that information elsewhere and link out from the docs instead, I think this provides a nice balance between discoverability and sustainability.