#25703: Create topic documentation for Expressions
-------------------------------------+-------------------------------------
Reporter: thatdocslady | Owner:
Type: | thatdocslady
Cleanup/optimization | Status: assigned
Component: Documentation | Version: master
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by thatdocslady):
Replying to [comment:3 jarshwah]:
> Thinking about this a little more, I think what we should be writing
topic docs on is "Customising the SQL generated by the ORM". Topic name to
be cleaned up.
>
> That's really the entire point of expressions. They let you customise
the query. Lookups and Transforms also help with customising the query.
Extra and Raw, to a lesser extent, also help with this. I think the topic
docs should make this as their focus.
>
> We can then link to Expressions API docs, Lookup/Transform API docs (of
which there is already topic docs on how to create your own and why), with
a light touch on extra/raw.
>
> Thoughts?
That makes absolute sense, actually. Similar to how we expanded the full-
text search docs to encompass all-things-search, we can approach
expressions from the functional/user perspective. So something like this:
1. Custom SQL operations with the ORM (title WIP) - Overview topic that
builds on the basic SQL topic and tells users what we can offer them to
extend/customize SQL with the ORM.
2. One or more use-case examples of expressions + queries to achieve
specific goals (for example, the reporting you wanted to do). These will
include scenario>goal>SQL snippet>result, much like a tutorial but
lighter.
3. Reference sections for APIs and further reading links as needed.
How does that sound? I'm planning to sprint on this on Sunday at PyCon CZ,
so if you can provide some basic/raw data for it by then, I can flesh it
out and hammer out a draft.
--
Ticket URL: <https://code.djangoproject.com/ticket/25703#comment:4>
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 django-updates+unsubscr...@googlegroups.com.
To post to this group, send email to django-updates@googlegroups.com.
To view this discussion on the web visit
https://groups.google.com/d/msgid/django-updates/070.0e873019ceecfcd771adc37ad59942c3%40djangoproject.com.
For more options, visit https://groups.google.com/d/optout.
