Step-by-Step V1 Overview
TL;DR
Preface
This is my first run at playing with tutorail design. It's a very early draft. I hadn't come up with the guidelines yet. In fact, going through this process is what helped me start getting them down.
Concept And Notes
(In no particular order)
- The core idea here is to make small changes and leave the code in a valid, running state at the end of each step.
- This approach leads to occastions of adding single lines of code that produce no visible functionality change. That is intentional. It allows for more fine grained explination of individual elements and makes it easier to catch typos via the increased frequency or running the code.
- This was my first run at this. Looking at it, I don't like the lenght of the pages. I've got an idea to play around with for another example where the snippets are contracted and then can be expanded to see the rest of the file context. The descriptive text would be moved under the snippets similar to a caption of a photo.
- Another mode that I haven't put in the example yet is an intentional error for in-between steps that can't be competed in a straight-forward way without them.
- The micro-steps include individual steps for creating code that wraps other content seperately from putting the internal code in place. (See steps 6, 7, and 8 which build up the `onChange` listener.)
- I've got syntax highlighting turned off as a test for the examples. The idea is to highlight the lines that change and have that be the only color in the sample to draw the eye more strongly.
- One intentional aspect of this appraoch is that each step is at it's own url so they can be bookmarked and linked to as references.
- The text I'm using for the descriptions isn't meant to replace actual well written documentation. It's directionally accurate, but largely a stub for real content.
- The size of the text in the descriptions for each step changes height. That causes the code block to move up and down the page. There are some designs that would limit this that would be ideal (e.g. side by side on screens that are large enough) that I haven't added for this basic example.
- I haven't edited this yet. Please forgive mis-spellings, mis-grammars, and odd turns of phrase.
- Another thing to add is `Next` / `Prevous` navigation so you don't have to click a specific number
- The focus of this example is on the code block and the general approach. The design of the navigition can be improved.
- I'm sure this isn't a new approach. Just another take on it. If you have similar examples, please send them my way.
- I would also remove the style calls from the code. If styling is needed, providing a single CSS file and telling folks to just drop it in seems a better option than having inline styles that add visual noise in the code.
- Thinking more about the length of files, it feels like a good goal would be to make files short enough that they don't need line numbers. That would reduce visual noise and avoid conflicts when folks doing the tutorial added extra white space lines are have a different formatter in play.
- The example is based on the React Router tutorial. Most of that original tutorial is done in small steps, but this section threw a lot of code out in one shot. I mis-typed some stuff and ended up having to bug hunt for a while. It was tough to triangulate where the issue was because of the number of lines that changes (19 in this case). That kind of thing burns mental energy and can be a huge blow to confidence. Hence this small-steps approach.
- You should be able to use this as a drop in replement for the Search Params step in the original tutorial. (It's possible I busted stuff when doing the formatting. If some see something that doesn't work, let me know.)