Third-party packages in Django's documentation
The Django community is doing itself a disservice by not mentioning third-party libraries more prominently in the documentation.
Django’s vibrant third-party package ecosystem is critical for all Django applications. One of the most popular forum thread is literally about third-party packages! It’s also a question featured on all of the Django developer surveys (2020, 2021, 2022, 2023, 2024).
So let’s double down on something that helps make Django successful!
Featuring third-party packages in the documentation can help new and experienced developers. These mentions will act as educational hooks, helping people to realize a plethora of features are only a dependency away. It also serves as a way help experienced, but new to Django, developers to more realistically evaluate a Django project.
Why do we hide this benefit away?
I’ve heard two main arguments.
- Curation is hard
- Mentioning specific packages will stifle innovation
Curation is hard
Deciding who gets featured is definitely a problem. We’re a community that wants to uplift each other, but there’s also the reality that some packages aren’t production ready. Someone needs to do that evaluation. However, we don’t want EVERYONE in the community to do that evaluation. That’s overkill. Side note, Adam Johnson has an excellent post on how to do that evaluation.
Beyond new packages, there are packages that may no longer be maintained. It’s difficult to make the decision to say, “this package, while once very robust, is no longer to the standard we hold.” Again, we want to be uplifting and curation will force interactions that are inherently not.
Thankfully, the Steering Council has started a new effort to feature popular third-party packages and resources. Perhaps we continue that path and ask the Steering Council to evaluate new packages once every six months. Given that group of people is elected by the Django community, they should always be a trustworthy group to make this decision.
Admittedly, this will create some noise for the Triage and Review team with people creating tickets and PRs to add references to their packages, but we’re probably talking about one or two a week. This should be a reasonable cost to incur.
Considering the curation has already occurred, it feels unwise to continue to limit ourselves because curation is hard. Let’s take advantage of the work the Steering Council has done and make it a force multiplier for the community.
Mentioning specific packages will stifle future innovation
This seems to be at odds with the software development trope of rebuilding the wheel. I mean, there’s a reason we have to tell ourselves and others to not rebuild the wheel. So yes, there’s a case in which someone will see X package that exists and think, “Oh, I don’t need to create Y, since X already exists.”
I’m not sure that’s a bad thing though. Creating a software package to the point of having it be well-used is difficult to do. It takes a lot of time and energy. Helping people realize the reality of the situation earlier can align people to the work they want to do.
Then there are the countless cases where something already exists and a person wants to go ahead with their version anyway. Sometimes it’s because they want to scratch their own itch. Sometimes it’s because they just want to do it their way. In any case, they have a personal incentive to do it that’s not tied to the fact that others have already done this.
We have many programming languages and many frameworks. People are rebuilding wheels all the time. To think that we’re going to stop those people from wanting to innovate and try something new is unrealistic. After all, developers are going to develop!
Linking to djangopackages.org grids
A potential next step would be to update our documentation to link to djangopackages.org’s grids in specific areas. This makes a lot of sense as it allows every library creator to be featured on the grid and offloads work for Django contributors and Fellows to the community members who maintain djangopackages.org (and a big thank you to you folks!). This opens the path to providing equal visibility to every package that’s relevant to an area.
This matches how other libraries manage community projects. Laravel does this with Socialite / OAuth providers, as well as managing notification delivery channels. Phoenix does this when describing telemetry reporters.
While this seems to avoid the curation conundrum, I don’t think it does. We still need to choose which grids to feature and where. Those decisions will likely come based on which packages are stable and robust. It makes sense to reference the grid on component libraries somewhere around the Django Template Language in the docs, but at what point should we include a grid on Django AI MCP plugins?
Once again, we should turn to the Steering Council’s list of community projects for the same reasons from before. It’s a group of elected people from the community, the group will have turnover so the list will go through different perspectives and they will always be invested in the community.
If we choose to go the route of featuring grids in the documentation, the grids should start by being based on the packages that the Steering Council is already highlighting.
Make your opinion known
If you’re still reading this and would like your voice heard, please participate on the New Features repo issue for this. Please be sure to use the emoji reaction and add a comment if you have a different perspective to provide.
I’d personally love to see us do more in this area, but the community needs to be in support of it. So let folks know what you think!
If you have thoughts, comments or questions, please let me know! You can find me on the Fediverse, Django Discord server or via email.