Tutorial Flow
-
Whenever I follow a tutorial that starts with a configuration file first and then goes on to setup the dependencies to make that configuration file work, my brain is always telling me it feels backwards. I read the the configuration file and see what I haven't set up and my brain is like, 'you can't use this configuration file yet because you haven't set up the dependencies.' For me, the natural flow seems like it should be to set up things in order of dependencies, and then putting the config file at the end would tie everything together and when you read it for the first time you can check off in your head that you have everything set up.
However, I'm wondering if having the config file at the beginning is actually the proper way to do the tutorial, and I should work on training my brain to accept that. The benefits I see are
-
It becomes the overview of the goal. The config file is the main setup, the other steps are just tasks to accomplish that, putting the config file first means that some trivial part of the setup doesn't get the prime spot, and we get a clear picture of what we are trying to accomplish.
-
It engages the brain. As Don Jones would say, our brains are trained to be collectors. If we read the config file first and see things we don't have yet, that triggers something in the brain and then we are actively looking to collect the information we know we don't have yet.
Should my brain feel this way is backwards, is that intentional to help with the learning process? Or does it say something about the way I think that may actually work against me in some situations?
-
-
@flaxking No, this is never a good way to start, and almost always ends in a non working whatsit when done. If you're writing a tutorial, start at the beginning (dependancies). Look at some of @scottalanmiller's things he's written here, it's what I've based all of my tutorials/walk throughs on.
-
@travisdh1 said in Tutorial Flow:
@flaxking No, this is never a good way to start, and almost always ends in a non working whatsit when done. If you're writing a tutorial, start at the beginning (dependancies). Look at some of @scottalanmiller's things he's written here, it's what I've based all of my tutorials/walk throughs on.
Mine are also good example detailed start to finish.
-
@JaredBusch said in Tutorial Flow:
@travisdh1 said in Tutorial Flow:
@flaxking No, this is never a good way to start, and almost always ends in a non working whatsit when done. If you're writing a tutorial, start at the beginning (dependancies). Look at some of @scottalanmiller's things he's written here, it's what I've based all of my tutorials/walk throughs on.
Mine are also good example detailed start to finish.
#truth
-
I believe most tutorials are written to get something up and running with as few steps as possible, assuming there will be no variances that create differences from the norm in a lab, and the person who wrote the tutorial expects the person reading the tutorial only wants it to work, rather than understand how and why it works, along with how to configure it for different scenarios; and the the writer must also believe the reader has no issues with run-on sentences.
-
@JasGot said in Tutorial Flow:
I believe most tutorials are written to get something up and running with as few steps as possible, assuming there will be no variances that create differences from the norm in a lab, and the person who wrote the tutorial expects the person reading the tutorial only wants it to work, rather than understand how and why it works, along with how to configure it for different scenarios; and the the writer must also believe the reader has no issues with run-on sentences.
If you ever see one of mine like that, call me the fuck out on it.
-
@travisdh1 said in Tutorial Flow:
@flaxking No, this is never a good way to start, and almost always ends in a non working whatsit when done. If you're writing a tutorial, start at the beginning (dependancies). Look at some of @scottalanmiller's things he's written here, it's what I've based all of my tutorials/walk throughs on.
So why do I see many tutorials designed that way? If it's not done intentionally for some kind of learning benefit, what would cause someone to 'naturally' structure it that way?
-
@flaxking said in Tutorial Flow:
@travisdh1 said in Tutorial Flow:
@flaxking No, this is never a good way to start, and almost always ends in a non working whatsit when done. If you're writing a tutorial, start at the beginning (dependancies). Look at some of @scottalanmiller's things he's written here, it's what I've based all of my tutorials/walk throughs on.
So why do I see many tutorials designed that way? If it's not done intentionally for some kind of learning benefit, what would cause someone to 'naturally' structure it that way?
People do irrational things all the time, worse, some probably think it's a good idea, although it makes about as much sense as this run-on sentence.
-
@JaredBusch said in Tutorial Flow:
@JasGot said in Tutorial Flow:
I believe most tutorials are written to get something up and running with as few steps as possible, assuming there will be no variances that create differences from the norm in a lab, and the person who wrote the tutorial expects the person reading the tutorial only wants it to work, rather than understand how and why it works, along with how to configure it for different scenarios; and the the writer must also believe the reader has no issues with run-on sentences.
If you ever see one of mine like that, call me the fuck out on it.
Didn't read; sentence is too short
Oh, and I will, just for you!
