I don’t know of it’s the best place to discuss that but I wanted to report a minor issue with the tutorials.
I worked my way through the tutorial. Everything went fine until part 8 where we install the Django Debug Toolbar: the toolbar was not displayed on my views (i.e. the one created during the tutorial). After a quick search, I found that this is because if you follow closely the tutorial, the HTML code doesn’t include the <body> tag which is needed.
Maybe I have missed something or I could have realized that before but I was focusing on Django, not HTML. It’s briefly stated in part 3 that the tutorial uses “incomplete HTML” but I think I’m not the only one that missed this part (and it seems that this part confuses some people).
So I think that we could improve the tutorials on that point. Maybe we could just indicate in part 8 that it’s time to add the <body> tag if not done previously or maybe the template example could include a bit more of HTML.
I think that the handling of templates is something that is much better covered in the Django Girls Tutorial than here. (And it’s one of the biggest reasons why I recommend it in addition to the official Django tutorial.)
I think that there might be value in adding one more page to the tutorial to cover the basics of the templates - including the concept of extending a base template and blocks. <opinion>
I got confused by the dates and thought this was the forum post created by another person who ran into this problem yesterday and posted about it in discord.
edit: I just realized that somehow I was using the 5.0 docs and not the 5.1. I must have followed a link to the tutorial rather than going through the Django website. Not sure if there’s a better way to handle linking to the “latest” version of docs, because I’m sure there are a lot of stale/out of date links out there.
As I posted in Discord, I follow tutorials exactly, since I presumably don’t know what I’m doing, and don’t know what the tutorial is teaching me or what the tutorial is going to do next. Since I followed the tutorial exactly, I read the note about the templates being incomplete HTML, and I read the part about using complete HTML in my own projects, but the tutorial isn’t my project, it is yours, and I’m following it exactly.
This is further complicated by the fact that if you open Chrome developer tools, it can look like tags you didn’t write are there if you look at the “Elements” tab:
So, if you read the Django Debug Toolbar Tips page and get to the end of the first paragraph and read the part about needing a </body> tag, but don’t know that Django doesn’t include any tags you don’t write and if you look at developer tools rather than “View page source”, then you might not realize what’s going on, and waste a whole bunch of time checking settings and configs and changing Windows registry for mimetypes and a number of other “fixes” I read about while searching for a solution. I actually found the solution in an old reddit post.
I don’t think it’s too much to include one sentence or better, a note, that says something like:
Remember how we wrote incomplete HTML templates in Part 3? Django Debug Toolbar requires a complete HTML document, so you’ll need to add <body> and </body> tags to your .html template files in order to see it in action. You can read more about body tags here.
I’m seconding this request. We could and maybe should try adding diagnostics to the toolbar as well, but giving newbies some additional help and guidance in the official tutorial should be an easy thing to support, I hope.
I’m wondering if the tutorial shouldn’t be expanded with <!doctype html><html><body> and </body></html>, because it’s good practice to work with complete HTML documents, but that’s a different discussion.
I wouldn’t reopen the ticket as this is feedback on the 5.0 tutorial, before the recent updates from that ticket.
I also think the idea of making the tutorial examples longer to include complete HTML should be discussed independent of django-debug-toolbar.
If brevity is important, we should keep what we have now as we give hints the html is not complete and enough information you can check it’s installed.
If completeness is important, then we should update templates generally. We may want to consult the accessibility team also.
Thanks, that’s good to know! Unfortunately, to my point, that redirects to the actual version number in the URL, so someone copying/pasting the URL would have to know about that trick and manually make the change. I still think it is weird that the 5.0 documentation is working alongside the 5.1 docs, especially with 5.1 having these good corrections in it. I would have preferred whatever original 5.0 doc URL to redirect to 5.1.
Yes… it’s tricky. Folks using (say) 5.0 want to be able to view the docs for the version they’re using, so just redirecting to the latest version wouldn’t fly.
There’s a banner if you’re using an EOL version. We could maybe add similar for “not the latest version”, but we’d need to consider how that would be phrased for folks on the LTS (which is often what people do want). I think @CodenameTim is thinking about this.
This feels like a case where we should be open to backporting a change to all currently supported and relevant release branches. Maybe we limit it to “bugfixes”?
That’s a bit of a different topic though and may warrant a separate thread.
Extending the backport policy to include docs versions outside of the mainstream support phase is much more of a lift than I suspect you think it sounds.
