A Full Critique Of The Django Static Files Documentation ======================================================== 1. The entire initial premise is wrong: "Django developers mostly concern themselves with the dynamic parts of web applications". Every web application uses insane amounts of static files referenced in their HTML. In development you *have* to deal with static files and actually all a Django app does is convert data bases and resources into "static" HTML that references CSS and Javascript. Right off the bat this is just wrong. 2. Nobody who does web development thinks about static files the way this document is structured. When you work on a web app you have two modes: 1. I'm fucking using localhost and I need to edit files on *this* computer so I can make the UI work. 2. I'm going to deploy the UI developed in #1 to a server and the goddamn static files better show up faster without me changing my templates. These docs fail at the most basic level because they schizophrenically try to mix instructions for development mode with runserver and deployment mode without any instructions 3. This document claims to tell me *how* to deploy my static files, but has one *single command line example*. How in the hell can it possibly tell me how to actually do something with commands on a server if there are no example commands for me to follow? 4. The entire "basic" usage section says what to do but not exactly how to do it. For example it says "Make sure that django.contrib.staticfiles is included in your INSTALLED_APPS.". Ok, *how* does someone do that? What do you edit? 5. "Put your static files somewhere that staticfiles will find them." What the hell is "staticfiles"? Is that a command? Is that a module? Where do I find it? What variables control it? WTF is it? Is it a magic elf that fixes static for me so I can watch TV? 6. "You’ll probably need to refer to these files in your templates." Refer to what? What setting do I set? STATIC_URL? What uses that? The templates? The runserver? What is an example STATIC_URL setting? 7. In the entire description of the first Basic Usage section not a single thing is mentioned about *where* I put a static file and not a single directory listing. Do I put it in /static/ at the root, in each app, both, nether? 8. In the next section you have variables but you don't say: 1. What parts of django use what variable. Is STATIC_ROOT used by runserver to figure out where to get static files, or is it only used by the collectstatic command? If it's only used by collectstatic then why the hell isn't it just a command line option to collectstatic? 2. Can a brother get a diagram?! Seriously you got 4-5 variables (more if you include MEDIA_*) and not a single diagram showing what is pulled from where to make static files available. 3. You show the collect static command but don't explain any caveats of its use, how it works, where it takes things and puts them, no examples of actually using it, nothing but how to run it. Why can't you give an example of "Imagine you've got static files in X, Y, Z and they need to go on the server at J. Collect static will then..." Nothing just "run dis it worked!" 9. Then you have information about how to use static files in templates *after* all the information for how to deploy them? You don't even describe how STATIC_URL shows up in a template except to mention a context processor. But the stupidest part is this goes in a description of accessing static content while developing and there for goes first. 10. The whole section "Serving static files in development" makes no sense. I never had to do this crap to serve static files, so is this for development mode or is this another other kind of development mode. Why doesn't this start with a particular problem and then give this as a solution? What is this solution solving? Why is the damn warning about DEBUG=True at the end instead of just part of the steps of the solution? 11. The entire document fails to give even a single reasonable step-by-step description to do anything it claims to teach. It simply points people at other similarly anemic documents and vaguely defines what each thing is without coming close to taking someone from 0 configuration to a working development environment and then from that to a working deployment on a real server. 12. All of the settings.py variables given are lacking key pieces of information I need to know how and when to use them. Primarily: 1. What part of django uses the variable? 2. How and where do I use the variable? 3. What are appropriate settings for the variable, with examples? 4. What are the defaults for the variable? 5. What can't the variable be set to? 6. When should I be setting this variable? 7. What are the security concerns associated with the variable? Recommendation For Improving This Document ========================================== It's my opinion that this document is vague and pointless because the feature it describes is just weird and undefined. I believe the static files feature would be better if it just picked a directory where static files are always put by default, and then let me put a deployment location on the collectstatic command line. But, if you're going to keep the feature out of arrogance that you've implemented it then at least take the time to describe *how* to use the damn thing the way a real Django programmer uses it. To do that you should rewrite the document in the following way: 1. Introduction should describe what the document will teach you how to do and not editorialize on what programmers do with static files. 2. Break the document into four sections: 1. Configuration Overview 2. Development Mode 3. Deployment Mode 4. Exceptional Cases And Gotchas 3. Ditch the entire discussion of the old upgrading from static files and make that a separate document. 4. Each section should go through a *complete* walk through of taking someone from a fresh new django application to a working runserver with static files and then a working deployment to at least one sample server. Apache or nginx preferred, but make it a concrete actual server with that server's configuration. 5. Every configuration variable used in this should have the list of things I mention in #12 in another document with links off each variable to that document. 6. Show *actual* settings.py files and *actual* directory structures from *actual* Django programmers. This whole document smacks of Django guys keeping shit secret sauce so they can get consulting gigs. 7. Finally, hand this to a newbie developer and have them go through it then fix *anything* they hit as a stumbling block. Even better if you can find a RoR developer who is reasonable enough to try and do this to help you out.