Documentation Consistency Proposal for Django

Based on your detailed analysis of the current documentation inconsistency regarding headers and table of contents entries, I can provide some thoughts on your proposal.

Current Situation

You've correctly identified that Django's documentation has inconsistencies in how class/method headers are handled:

• Some pages like the SchemaEditor have manually added headers for classes/methods
• Other pages like the Paginator docs don't have these headers
• The toc_object_entries setting is currently set to False to avoid duplication

Evaluation of Your Proposal

Your proposal to improve consistency makes sense, especially considering the benefits you've mentioned:

• Improved on-page navigation
• Better search ranking through TOC matches

Between your two approaches:

Option 1: Add missing headers + update contributing guide

• Pros: More control over header text and formatting
• Cons: More maintenance burden, more code, higher barrier for contributors

Option 2: Set toc_object_entries to True + remove duplicates

• Pros: Reduces code, simplifies contribution process, more maintainable
• Cons: Less control over specific header text

Recommendation

Option 2 seems more aligned with Django's documentation philosophy of maintaining consistency and readability while making it easier for contributors. The Django documentation already emphasizes treating documentation like code and improving it frequently, so reducing barriers to contribution is valuable.

If you proceed with Option 2, you might want to:

1. Document this change in the contributing guide
2. Create a plan for removing duplicate headers from existing documentation
3. Consider a phased approach to avoid disrupting too much at once

This approach would be consistent with Django's documentation organization principles, particularly for Reference guides which are meant to be technical and focused.