Are my tutorials too dense?
Hi!
recently i started to write articles in my blog, last one is a programming tutorial, but i feel like is too dense, the ratio code/text maybe is too low? (even adding comments to the code snippets)
I would like some opinions about it, thanks!
This is the post
https://pixo.sh/creating-a-fancy-stepper-component-in-react/
Trending on Indie Hackers
The tutorial appears to be nicely explained. However, I found it difficult to focus because of typography ...maybe it’s just me .....but I feel that white background with large modern fonts and better spacing , specially for programming tutorials where there is a lot of code with accompanying text, makes a huge difference in readability and staying focused.
Yeah snippets typography is something in my todo list, currently i use Space Mono from google fonts.
I like the “dark” theme, but maybe i can consider a light mode since the CSS is pretty simple right now
Thanks for your help and time!
Okay, opinion - but keep in mind I have Very little knowledge of coding.
I think you need some sort of intro. I was actually taken off guard by no leeway into the content.
Yes, there's a lot of code, but I think you could space it better.
Instead of huge code and then tiny bits of text squeezed in between - use some spacers. Simply making some of those little stances in the middle of the code into stances with actual space above and below the code boxes is going to be wya nicer on the eyes. I'd look a bit into formatting content for easily readability.
Personally, I feel like there is more text needed 🤷♀️ am I code expert, but I really was struggling to follow. You'd have paragraphs such as "access such N such file" and then the code is below, but there's no reference to where in the file, or the million other little details to how to get to that file. I get not wanting to write it all out (especially cause it would get redundant) but you should at least link to where more information cna be found for these sort of basic questions - that'll give you more text to work with.
Lastly, be more you! I write fairly have duty content on marketing and seo, but I find I can make it much more enjoyable for the reader simply by making my text more Ike me talking and less like a textbook. I recommend maybe trying speech notes and voice recording you tutorials - not only will you probably have more text, but it'll be a lot more personable.
Best of luck! Hope this helps!
Well, actually the “no intro” is on purpose, in this particular case
An Stepper is not a so common UI component, is not a popular one like an Input or a collapsible. So this way people can go into the article and notice easily what im talking about.
Also since the result of the guide is really visual, i though a gif could be useful to clearly see what you will get at the end
I think i need to still find a tone to write my posts, i didnt write this the same way i explain concepts to my students, i really like your idea of speech notes, i will for sure start to record my classes and try to emulate them since i validated long ago that way of teaching
Thank you for your feedback and time!
Its perfect
Maybe it is the way I tend to read programming tutorials, but I am lazy and do a lot of skimming. I had to slow down a lot to comprehend what you had written.
I wouldn't call it too dense, but maybe not using markup to your advantage.
And when you mention files or function names referring to code, you could
highlightthem with the single backtick (assuming you're using markdown).---
I get lost as you jump around code blocks to different files. What is the intention of your snippets. Is it for full copy/paste in every case?
I'm not always sure where to look and what is relevant code. Sometimes you're doing more than one thing at a time. Your description of changes are all at a high level, so I end up having to skim the entire code to find what change you talk about.
---
My feedback re: code blocks:
Where there are comments, my eyes are drawn to those first bc of the syntax highlighting.
Maybe giving filenames to your code blocks will help contextualize what I'm looking at? I'm trying to follow along but I end up doing a lot of background processing about what I'm seeing.
You're dealing with 3+ files and the only way I know where I am in the project is to read the entire body text above the block and parse out the names of any functions you reference.
I can share two ideas I'm playing around with and see what works for you.
---
I apologize if this feedback is too direct.
I think your animations are very helpful. Your tone is friendly and conversational.
Yeah definitely i need to name the snippets and improve the formatting
What do you think could be a solution for the comments problem?, i consider them in some cases even more important than the code, sometimes is hard to write self explanatory code.
Thanks! And no worries, your feedback spotted things that i didn’t notice at first
I don't think the comments are a problem. I was intending to point them out because I think they can be leveraged when you want to hold your reader's hand in a specific section of code.
You can probably even be overly verbose in the comments as an extension of the conversation.
Looks like a good and thorough tutorial! I normally prefer them to be dense.
Have you ever looked up a recipe online and you had to read through 10 pages of someone's life story before you could actually see what you need to do? That always feels like more work!
Maybe in some cases you could even condense it a bit more if the readers will typically be familiar with the steps to start a new project, or if some of the code is kind of standard boilerplate.
That way you can highlight the really unique parts so people can learn the concepts you're working with through your examples, with links to the full code if they want to read it line by line.
That sounds good, i assume not everyone is up to date with the latest and more practical ways of doing X, i think when we learn something basic as a dev we stick to that way to do that thing, and we don’t invest time in learning better ways to do that or other ways that fit into what we need to do better.
For example i didn’t know that create react app now has a documentation site, because i don’t go through the docs too much, i learnt it long ago, and when i wrote the guide, i went to the docs and discovered that now i can create TS ready react apps directly from the CLI.
So these parts acts as a reminder of what is a new way of doing X in case you didn’t know, or maybe a better way to do it, and if you are a beginner, you can go through that step without having to google what im talking about.
I don't know React, so I can't speak to that, however, if I were going to learn it how to use it, I'd try to use this tutorial. I think you have a good mix of code/text for the most part. The only thing missing, to me as a know-nothing of React is what this is for.
I figured it out by the end, but just looking at it, but without scrolling down, I would have been lost.
Thanks! Your feedback helps me a lot Ryan
This post was not intended to be for beginners tho, maybe i should tag it or mention it in the post?
👍