When I read the Django documentation or a tutorial, I sometimes wish it was just a list of commands and not a textual description which tells you which programs to open, which files to edit, where to save them etc.
So I made a demo how this could look like. It shows how to create a Django web application from scratch. Starting with a fresh Debian installation or container:
Do you find this useful? If so, we could collaborate to complete / expand it.
I’m curious, who are you envisioning as the target audience for this?
Are you familiar with Cookiecutter? (Also see Django Packages : Cookiecutters)
If so, is there some overlap here, or are you targeting a different audience?
The audience would be people like me who:
1 - Like to completely understand their codebase
2 - Like to have only code in their codebase they actually use.
The way this tutorial would be used is two fold:
You can just read it. Then afterwards you learned a bunch of concepts about Django with absolutely no ambiguity. Since it is a working script, you never need to ask yourself something like “I wonder if I have to do xyz to make it work”.
Or you can customize the script to your likes and have your own “start a project” script. Only using the parts of the script which you need.
Regarding the Cookiecutters link: How does it help if you want - say - a minimal working Django installation with only routing, templates and user accounts?
Different people are coming to Django from different levels or different starting points. Someone looking at Django with 10 years of Python experience is going to have a different baseline from someone without any Python experience at all.
Not only that, but getting a viable Django environment working from scratch is going to vary greatly between Windows, Mac, and various shades of Linux.
It seems to me that a list of commands with no real context greatly limits your potential audience.
Your milage may vary. But after answering questions here for the past year or so, I’ve found very few people and probably zero beginners who manage to “learn a bunch of concepts about Django with absolutely no ambiguity” just by reading the code. At a minimum, it assumes a fairly strong Python background.
My experience has demonstrated to me, that in the absense of a clear explanation, people will make assumptions about why something is needed or how something works - and fewer than 25% will make the correct assumptions. Django is not trivial. There is a lot to it - and a fair amount of that is rather nuanced or subtle.
To pick just one example from your starting point - you have:
cat << 'EOF' >> settings.py
INSTALLED_APPS += ['mysite']
EOF
This is going to append mysite to the end of INSTALLED_APPS.
Yet, there are at least 4 situations I’m aware of where the order of INSTALLED_APPS is important, and you would want mysite at the beginning of the list, not the end.
Regardless, I’m not sure how just reading that code is going to convey the importance of the order.
You will have learned that you need to put an element in the list, but unless you make the guess that the order might be significant and know to look for it in the docs, you may never be exposed to the idea that the sequence is important - until you run into one of those cases where it causes you a problem.
That’s the purpose of Cookiecutter. And so to continue on…
You either find an existing Cookiecutter, such as the ones referenced in the previous djangopackages.org link (modifying it if desired), or you can build one yourself with exactly the features you need or that you want to share with others.
So, I’m pointing all this out not to say that your idea isn’t worthwhile - more maintained tutorials are always better than fewer. However, there already is an existing framework (Cookiecutter) for generating the type of script you describe - and you might find an existing implementation of what you’re looking for.
Is it? I would have thought only this one line of the tutorial might be different on different OSes:
docker run -v $(pwd):/var/www --rm -it -p 80:80 debian:11-slim
From there on, everyone should be in the same environment.
Seems to me that the installation process of docker itself is going to be different by OS.
(Leaving aside for the moment the potential issue of even being able to install docker in a corporate environment that doesn’t grant administrative authority to unapproved personnel - a painful situation with which I am all too familar.)
And if you’re going to go that far, why not just create a docker image with the application installed?
In any event, that’s really a side-issue to my main point.
My question is really wondering how much can actually be learned by just looking at the source code without any guidance, given the variety of backgrounds and experiences people have.
I can’t remember when I last met a developer who does not have Docker experience. In fact, I can’t remember when I last met a developer who does not have it on their laptop already.
My target audience would primarily be makers who run their own product and already have decades of programming experience. People like me. I learn fastest by reading code.
Personally, I would love to have this type of tutorial side by side for all the major web frameworks. Django, Flask, Laravel, Symfony, NextJS etc. And have it updated yearly or so. So with a quick glance I can get an overview of the current state of affairs in starting web projects. And be able to just copy&paste one of the approaches into a fresh Debian installation and have it running.
You’ve now met at least one. (me)
Docker experience? Sure, our last 6 deployments have been containers.
On our development systems? Nope. By number of installs, the majority of my deployment environments are essentially embedded systems for which docker would introduce just another layer of overhead for which there would be no benefit.
I could in theory also introduce you to about 1,200 web developers from another large multi-national financial services corporation that don’t. (And that’s only what I have direct personal knowledge of - I’m sure they’re not unique.)
Now, regardless of the above -
That’s precisely the point of Cookiecutter, except it’s not intended to be limited to Debian. It’s not a Django-specific tool, either. Someone so inclined could produce “rapid-start” cookiecutters for those frameworks among others.