Code

Opened 14 months ago

Last modified 6 months ago

#19898 assigned New feature

Document why/when of class-based views

Reported by: estebistec Owned by: estebistec
Component: Documentation Version: master
Severity: Normal Keywords: docs sprint2013
Cc: Triage Stage: Accepted
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: yes
Easy pickings: no UI/UX: no

Description

The documentation for class-based views is getting better, but it's missing an introductory discussion of why and when you use them. Specifically, the goals of such a narrative should be:

  • Practical context for choosing CBVs vs. FBVs
    • Usage patterns appropriate to class-based views
    • List of helpful, concrete decision points from the above discussion

Hopefully this can be something that people point to for diffusing absolutist arguments for CBVs or FBVs, and the community can start to agree when each is right (a bit of a grandiose goal, yes, but it should be possible).

New documentation that may arise out of the above needs:

  • How to test class-based views (and comparison with testing FBVs)

Ticket #19227 aims to provide visualizations code flows in class-based views and so may interact with some of the changes made on this ticket.

Attachments (0)

Change History (12)

comment:1 Changed 14 months ago by timo

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset

#16807 contains a bunch of text that may be useful to build on for this.

comment:2 Changed 14 months ago by estebistec

Thanks, I'll take a look at this.

comment:4 Changed 14 months ago by estebistec

From the intro text on the topic index page, there will likely be two new pages:

  • usage-patterns
  • testing

/plan

comment:5 Changed 14 months ago by jacob

  • Triage Stage changed from Unreviewed to Accepted

comment:6 Changed 14 months ago by estebistec

  • Keywords sprint2013 added

comment:7 Changed 14 months ago by estebistec

  • Owner changed from nobody to estebistec
  • Status changed from new to assigned

comment:8 Changed 14 months ago by estebistec

Welp, I should have figured working on CBV docs might not be easily wrapped up in a weekend. So I'm already assuming that this is only the start for this effort and I'll plan to continue and see it through. The biggest thing with a larger doc effort like this is that I need to do the due diligence of having others check perspective and voice of the narrative, in addition to commenting on the clarity of the details.

I think I've got some decent content, but I'd like more compelling examples for usage patterns, as I don't think I'm yet succeeding in differentiating class and function based views in a way people haven't already discussed, save for maybe my testing discussion.

So, core devs, if you have a moment I wouldn't mind some comments on my current direction before I continue.

My current efforts live in a pull request here: https://github.com/django/django/pull/840

comment:9 Changed 14 months ago by estebistec

Also, I'd like to do a survey of all the examples in existing CBV docs and make sure they are complete and independent (meaning views are wired to URLs, all necessary imports are present, etc.) That'll come after I get this new usage-pattern page worked out better.

comment:10 Changed 13 months ago by aaugustin

  • Component changed from Uncategorized to Documentation

comment:11 Changed 13 months ago by aaugustin

  • Type changed from Uncategorized to New feature

comment:12 Changed 6 months ago by timo

  • Has patch set
  • Patch needs improvement set

Add Comment

Modify Ticket

Change Properties
<Author field>
Action
as assigned
The owner will be changed from estebistec to anonymous. Next status will be 'assigned'
The ticket will be disowned. Next status will be 'new'
as The resolution will be set. Next status will be 'closed'
Author


E-mail address and user name can be saved in the Preferences.

 
Note: See TracTickets for help on using tickets.