Opened 9 years ago

Last modified 3 weeks ago

#25703 new Cleanup/optimization

Create topic documentation for Expressions

Reported by: Mikey Ariel Owned by:
Component: Documentation Version: dev
Severity: Normal Keywords:
Cc: josh.smeaton@…, Ülgen Sarıkavak, Clifford Gama Triage Stage: Accepted
Has patch: no Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: no UI/UX: no

Description

Currently this feature has the following docs:

Conditional Expressions - Reference document that contains descriptions and examples of conditional expressions https://docs.djangoproject.com/en/1.8/ref/models/conditional-expressions/

Query Expressions - Full reference about all expressions https://docs.djangoproject.com/en/1.8/ref/models/expressions/

Proposed new content:

  • Overview and benefits of expressions
  • Use-case example(s)
  • Tutorial (move from ref and expand)
  • General guidelines and limitations

Change History (11)

comment:1 by Mikey Ariel, 9 years ago

Owner: changed from nobody to Mikey Ariel
Status: newassigned

comment:2 by Tim Graham, 9 years ago

Triage Stage: UnreviewedAccepted

comment:3 by Josh Smeaton, 9 years ago

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?

in reply to:  3 comment:4 by Mikey Ariel, 9 years ago

Replying to 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.
  1. 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.
  1. 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.

comment:5 by Josh Smeaton, 9 years ago

I'll try and put something together by then. What exactly are you after? Use cases, API usage, and SQL (your point 2 above)? What else can help?

in reply to:  5 comment:6 by Mikey Ariel, 9 years ago

Replying to jarshwah:

I'll try and put something together by then. What exactly are you after? Use cases, API usage, and SQL (your point 2 above)? What else can help?

Great, thanks! Other than what you mentioned, it might help to have links/references to existing basic SQL docs so that I can do a comparison and build an "upsell" for the extended functionality.

comment:7 by Josh Smeaton, 9 years ago

Sorry, I haven't had a chance to do very much here. I started writing code with some comments the other day that I'd planned to circle back to and write some prose for. Apparently jetlag is a thing though. See attached what I started with. Hopefully there are some knowledgeable django people at the sprints that can help out.

Here's where I got to: https://github.com/jarshwah/expressions_talk/blob/topicdoc/expressions/topicdoc/models.py

Not sure how helpful that's going to be on it's own unfortunately.

in reply to:  7 comment:8 by Mikey Ariel, 9 years ago

Replying to jarshwah:

Sorry, I haven't had a chance to do very much here.

You and me both ;) turns out I need to catch up on my ORM lore before I can tackle this content, but I started researching and will ping you again soon with NEEDINFO as needed. Cheers!

comment:9 by Mariusz Felisiak, 4 years ago

Owner: Mikey Ariel removed
Status: assignednew

comment:10 by Ülgen Sarıkavak, 8 months ago

Cc: Ülgen Sarıkavak added

comment:11 by Clifford Gama, 3 weeks ago

Cc: Clifford Gama added
Note: See TracTickets for help on using tickets.
Back to Top