#37051: Improve the map of documentation on Django's home page
-------------------------------------+-------------------------------------
Reporter: Daniele Procida | Owner: (none)
Type: | Status: new
Cleanup/optimization |
Component: Documentation | Version: 6.0
Severity: Normal | Resolution:
Keywords: | Triage Stage:
| Unreviewed
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Daniele Procida):
* has_patch: 0 => 1
Old description:
> In general, the documentation home page does an outstanding job of
> unfolding Django’s documentation content in a topographical fashion –
> it’s like opening a map and seeing the terrain laid out in front of you.
>
> It's rational, compact and shows the relationship of different concerns
> to each other very effectively.
>
> However some of the rationality frays at the edges, and it's not
> maintained all the way down. Currently, it exposes, in order:
>
> * [https://docs.djangoproject.com/en/6.0/#first-steps First steps ]: the
> **entry-point**
> * [https://docs.djangoproject.com/en/6.0/#the-model-layer Models, Views,
> Templates]: these are key **conceptual and functional layers**
> * [https://docs.djangoproject.com/en/6.0/#forms Forms]: forms is a
> **feature** (something that Django offers you, that isn't a core of its
> architecture – you could imagine Django without it)
> * [https://docs.djangoproject.com/en/6.0/#the-development-process The
> development process]: **development lifecycle activity**
> * [https://docs.djangoproject.com/en/6.0/#the-admin The admin]:
> **feature** (it belongs with Forms)
> * [https://docs.djangoproject.com/en/6.0/#security Security]: a **quality
> demand** (something we want from Django, and want developers to achieve)
> * [https://docs.djangoproject.com/en/6.0/#internationalization-and-
> localization Internationalization and localization]: **feature**
> * [https://docs.djangoproject.com/en/6.0/#performance-and-optimization
> Performance and optimization]: **quality demand**
> * [https://docs.djangoproject.com/en/6.0/#geographic-framework Geographic
> framework]: **feature**
> * [https://docs.djangoproject.com/en/6.0/#common-web-application-tools
> Common web application tools]: a collection mostly of developer-facing
> **features** in no particular order
> * [https://docs.djangoproject.com/en/6.0/#other-core-functionalities
> Other core functionalities]: another collection without a strong uniting
> principle
> * [https://docs.djangoproject.com/en/6.0/#the-django-open-source-project
> The Django open-source project]: **contributing to Django**
>
> I propose reworking this map of Django's domains of concern so that
> things like each other are closer together. For example: **features**
> (e.g. Admin, Forms, GeoDjango), **quality demands** (Security,
> Performance) and so on.
>
> Here's a [https://docs.google.com/document/d/1hCwtXEtIU13Yq5JRsuuWW-
> 0bLkT44xFpoDQ_eSv4vfs/edit?tab=t.0 sketch of the new arrangement of
> domains of concern]. It attempts to achieve a balance of rationality,
> pragmatism (no heavy-handed application of rules if it would produce
> something awkward) and aesthetics (it should provide a good experience,
> feel good and even look right).
>
> It orders topics as:
>
> * entry-point
> * conceptual and functional layers
> * features
> * resources and interfaces (a new grouping, concerned with Django's
> access to the world outside it)
> * quality demands
> * development lifecycle activity
> * contributing to Django
>
> and sometimes uses those categories as actual titles too.
New description:
In general, the documentation home page does an outstanding job of
unfolding Django’s documentation content in a topographical fashion – it’s
like opening a map and seeing the terrain laid out in front of you.
It's rational, compact and shows the relationship of different concerns to
each other very effectively.
However some of the rationality frays at the edges, and it's not
maintained all the way down. Currently, it exposes, in order:
* [https://docs.djangoproject.com/en/6.0/#first-steps First steps ]: the
**entry-point**
* [https://docs.djangoproject.com/en/6.0/#the-model-layer Models, Views,
Templates]: these are key **conceptual and functional layers**
* [https://docs.djangoproject.com/en/6.0/#forms Forms]: forms is a
**feature** (something that Django offers you, that isn't a core of its
architecture – you could imagine Django without it)
* [https://docs.djangoproject.com/en/6.0/#the-development-process The
development process]: **development lifecycle activity**
* [https://docs.djangoproject.com/en/6.0/#the-admin The admin]:
**feature** (it belongs with Forms)
* [https://docs.djangoproject.com/en/6.0/#security Security]: a **quality
demand** (something we want from Django, and want developers to achieve)
* [https://docs.djangoproject.com/en/6.0/#internationalization-and-
localization Internationalization and localization]: **feature**
* [https://docs.djangoproject.com/en/6.0/#performance-and-optimization
Performance and optimization]: **quality demand**
* [https://docs.djangoproject.com/en/6.0/#geographic-framework Geographic
framework]: **feature**
* [https://docs.djangoproject.com/en/6.0/#common-web-application-tools
Common web application tools]: a collection mostly of developer-facing
**features** in no particular order
* [https://docs.djangoproject.com/en/6.0/#other-core-functionalities Other
core functionalities]: another collection without a strong uniting
principle
* [https://docs.djangoproject.com/en/6.0/#the-django-open-source-project
The Django open-source project]: **contributing to Django**
I propose reworking this map of Django's domains of concern so that things
like each other are closer together. For example: **features** (e.g.
Admin, Forms, GeoDjango), **quality demands** (Security, Performance) and
so on.
Here's a [https://docs.google.com/document/d/1hCwtXEtIU13Yq5JRsuuWW-
0bLkT44xFpoDQ_eSv4vfs/edit?tab=t.0 sketch of the new arrangement of
domains of concern]. It attempts to achieve a balance of rationality,
pragmatism (no heavy-handed application of rules if it would produce
something awkward) and aesthetics (it should provide a good experience,
feel good and even look right).
It orders topics as:
* entry-point
* conceptual and functional layers
* features
* resources and interfaces (a new grouping, concerned with Django's access
to the world outside it)
* quality demands
* development lifecycle activity
* contributing to Django
and sometimes uses those categories as actual titles too.
--
--
Ticket URL: <https://code.djangoproject.com/ticket/37051#comment:1>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.
--
You received this message because you are subscribed to the Google Groups
"Django updates" group.
To unsubscribe from this group and stop receiving emails from it, send an email
to [email protected].
To view this discussion visit
https://groups.google.com/d/msgid/django-updates/0107019da528714c-814948a7-d292-4543-afb1-88f7e3dc02ef-000000%40eu-central-1.amazonses.com.
