Opened 7 years ago

Closed 7 years ago

Last modified 7 years ago

#7374 closed (wontfix)

Mention simple_tag and inclusion_tag before manual parsing

Reported by: Waldemar Kornewald Owned by: nobody
Component: Documentation Version: master
Severity: Keywords: 990218e2c6e62b7a86619599
Cc: Triage Stage: Unreviewed
Has patch: yes Needs documentation: no
Needs tests: no Patch needs improvement: no
Easy pickings: UI/UX:


The current docs begin with explaining the complicated parsing system. This really gives the wrong impression that you always have to create parser and go through all those hoops every time you need a tag or do some simple logic that isn't available in the templates. I'd like to suggest that the documentation talk about simple_tag and inclusion_tag before turning potential users away with those complicated examples. Well, you nearly turned me away.

Attachments (1)

docs-simpletag.diff (1.4 KB) - added by Waldemar Kornewald 7 years ago.
minor improvement; on the long run the whole docs should be restructured

Download all attachments as: .zip

Change History (4)

Changed 7 years ago by Waldemar Kornewald

minor improvement; on the long run the whole docs should be restructured

comment:1 Changed 7 years ago by ubernostrum

  • Needs documentation unset
  • Needs tests unset
  • Patch needs improvement unset
  • Resolution set to wontfix
  • Status changed from new to closed

The way this is handled is consistent with other documentation and tutorials; first the "full" method of doing something is shown, then any relevant shortcuts are explained (e.g., the tutorial first shows you how to manually load a template, instantiate a context, render the template and return a response, then introduces the render_to_response() shortcut). This is generally a useful pattern because it ensures newcomers see how something works before using an abstraction which hides the underlying details. In that sense, it's somewhat like teaching someone a multiplication table before letting them use a calculator.

comment:2 Changed 7 years ago by bocman1 <Bocman1@…>

  • Keywords 990218e2c6e62b7a86619599 added

comment:3 Changed 7 years ago by Waldemar Kornewald

The current situation looks more like you'd have to learn group theory before learning the multiplication table because that goes into deeper detail. Seriously, the documentation makes templates look very ugly and complicated although they don't have to be that way. At least, you could mention that there is a simpler alternative before going into the ugly details (which is what my patch does).

Note: See TracTickets for help on using tickets.
Back to Top