Often when I read documentations or tutorials about a technology, I 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? It could be expanded to compare different frameworks setting up the same project. Django, Flask, Symfony, Laravel, NextJS …
Type A questions and their answers: How do I do this thing?
Type B: What decisions do I have to make about this thing, and in what way is it important?
This format is strictly type A. If you have a specific goal and the instruction list has a title that matches the keywords in your head for that goal, it will get you there.
There are two big problems with type A. The first is that it doesn’t educate you much on the type B questions that you might not even realize exist. The second is that if you next want to add, let’s say, Let’s Encrypt SSL certs to your Django app, the person who writes that tutorial has to have exactly the same conventions and opinions as the person who erote the Django-on-Apache tutorial, or else you’ll end up failing and not even know why.
There is a place for type A questions and their answers, but I think it’s best in shorter chunks to reduce dependencies and policy conflict.
Type B: I would think the comments have some educational value. Additionally, I was thinking about adding a second layer of comments. Which only appear when you hover the mouse over a command. So if you want to read deeper into the reasoning behind one of the commands, you can.
Would adding Let’s Encrypt really interfere much with the rest of the code? I would think the only thing of the existing code that needs to be changed is the 000-default.conf file and that can be simply be overwritten with a new block:
You have technical opinions. As long as you are consistent and cover all the topics, you are doing well.
But: J. Random Newbie is googling everything, not sticking to your site. They google for Django on Apache and use your instructions. Then they google for Let’s Encrypt on Apache and get someone else’s instructions, that works. Then they google for “Python Apache” and see that they should be using mod_python, not realizing that the article is from 2006. Now they have a nonfunctional Python web application and they don’t know whether it was the SSL config or the mod_python or the six half-configured WSGI servers that is the root of their problem, and they blame Django for being hard.
I have seen this many times. The XY Problem is real, and this sort of checklist is, as I said, good when you’re asking the right question and bad when you don’t understand what you’re asking.
My audience would be coders like myself. Who already have decades of experience in building projects.
When looking into a new technology, I learn more from reading the code of a skeleton project than from reading a tutorial.
But no skeleton project has just the right features one wants in a new project. Usually they are way to bloated and it is hard to say which parts can be ripped out. With the terminal based approach, one can go along the steps and stop just at the right amount of features. Skipping a feature in the middle would take some more mental effort. But after reading the script from top to bottom, one probably has a good grasp on how to do that. Better than in a normal skeleton project which is one big blob of stuff and you don’t know which files and lines have been introduced for what purpose.
I agree. When I’m reading online tutorials I often wish it was just a barebones project instead.
I consider this less a tutorial and more a cheatsheet, and I would seek to use it for the same reasons and occasions as a cheatsheet.
This is almost exactly how I document any workstation or snowflake or PoC server installation.
I try to also document the how and why of decisions and forks I make, for example that I picked apache2 over nginx simply because I found an out of the box usable hardened config at this or this url, and just went with it, or that rbenv have these pros and cons compared to rvm or asdf.
Great format, yeah! ♥
I love it, this is exactly how I take personal notes. It is simpler than the source (which may expand in complexity) is more efficient at communicating than a blog post, and is still searcheable.
How would you feel about breaking it into multiple code blocks? It might make it easier to visually skim the text (although at the cost of the ability to run it as a script).
My thinking was that the headings mark the sections. Like this one …
… marking the section about how to introduce templates.
Maybe I should remove the “Yay” thingies like this one …
… because it looks too much like a heading?
Update: I deleted the heart framed YAYs now. I think it makes it more clear what the sections of the script are.
That works! I’m just thinking aloud.
The color scheme really doesn’t work for me. The contrast between the dim grey of the comments and the bright green of the commands makes my eyes constantly want to go to the commands and ignore the text. I can’t get a grip on the full content, the colors cause me to skim even if I don’t want to.
I’d suggest playing around with colors, but also with indentation.
Interesting. Do you generally prefer dark themes or light themes?
Here is how GitHub renders the script:
Do you like this better?
Terminal-based documentation is great as a how-to guide. You know what problem you are solving, and you need a list of practical steps in order to solve that problem. I like that I can copy/paste commands to solve the problem. This is how I document my steps at work during operational issues, testing, etc.
As long as you tell your audience this is a guide for people who know what problem they are solving and just need a list of steps, they will be happy. That’s why at the top of docs and articles I write I put “learning objectives”, e.g. https://asim.ihsan.io/flutter-ffi-libsodium/, so that my audience know what they will be able to do by the end of the article without committing to reading it. You can “create” and “use” and “run”, but you won’t be able to “understand” or “compare and contrast” or “decide”.
Referring to https://documentation.divio.com/, I don’t think such a format is suitable for tutorials, explanations, or references. Or maybe, if you feel strongly that the format is suitable, for each of the quadrants you can justify why. Especially when a person does not know what problem they need to solve, such a format does not help. What is Django? What problem does it solve? What does Django have to do with Debian? What is Debian? What problem does it solve? Why am I using Docker? What problem does it solve? etc. Depends on your audience and their background.
After being lied to by source code comments for 20+ years I quite often do not register them at all. Your site’s color scheme contributes to that too – my eyes quickly jumped over the grey blocks.
To me, it would be better to have regular paragraphs interspersed with “this is your terminal running commands” blocks. Of course, that could be just me – maybe most folks actually read through comments.
It actually was my intention to make the comments stand back as much as possible. I even thought about only displaying them when you hover a command with the mouse.
The reason is that I usually prefer to read code and only read text if I am not sure what the code does. Because most of the time code is self explanatory. As Linus Torvalds puts it “Words are cheap, show me code”.
I had a mini ‘lightbulb’ moment when thinking about your question -:)
I think it would be great if Unix’s man system is enhanced with recipes and tutorials of this style.
The existing ‘man’s system not just non-interactive, it also misses ‘cookbook/tutorial’ style explanations. For those one has to go on the internet. Quality of material on the internet varies, and it is often inconvenient to incorporate suggested patterns into whatever you are doing at a command line..
If I understand it right, this was not your original are of interest – but may be you can think of ways of ‘wrapping’ the existing man system by something as interactive as you are thinking.
Another suggestion that I have, is that may be you can ‘parametrize’ the recipes so to speak.
Separate the ‘parameters’ out of the ‘solution’. Write out a narrative describing what parameters represent, and their ‘use-case’. Allow a reader to populate parameters, and then substitute the parameter values into ‘recipe snippet’.
This way you can leverage effective writing style (rather than hiding it in comments), while still providing a technical precise recipe.
What would be an example of such a parameter in the given Django example?
I thought about the $mysite parameter. But then I decided it would make the tutorial more complex and less readable. I think it is easy enough for the developer to do :%s/mysite/somethingelse/g