I'm starting to feel the need to know how to structure them visually in a way that makes the right information standout. Sorry, if this is not very clear.
For example, I find that just using headings is not enough for this.
Does anyone have any reading resources about how to use design to improve readability? I think that's basically what I need.
I have been typesetting texts as a freelancer for a while. Well structured texts basically set themselves.
Once you get the structuring right there might already be ideas which parts need images, illustrations or similar things to make the thoughts even more clear. It is crucial to note that images and illustrations always have to serve the flow of thoughts. Maybe the illustration can clarify something you didn't fully explain in the text, maybe it can give a slightly different angle etc. But it should always serve a purpose. Also consider that sometimes images can communicate something in a second that a text would need a page for. Sometimes it is just the other way around. Sometimes it is a small video, animation or interactive canvas. Choose the right media because it serves your idea (not because it looks fancy).
After a especially hard chapter the purpose can also just be to congratulate the reader like a price in a video game, so it must not be too serious. But know why you put things where you put them. So having a good designed tutorial is about developing design systems that serve the kind of information you happen to explain.
It makes sense that you collect screenshots and links of good examples for yourself and take them as a guide. Be it blogs, documentation actual physical books or whatever.
Always remember however that the most crucial thing is to structure the thoughts and get them into a flow. In the end a well structured text-only explaination will beat the best designed, fanciest explaination with unstructured thoughts most of the time.
- good design, fonts, spacing etc
- well cropped and annotated 4k screenshots, not too many, not too few
- a short gif or similar of the final result
- maybe something like Browser frame for a minimalist browser header and background colour
- code samples aren't too long and have syntax highlighting
Just some examples. Often when you go "oh wow this is a really well presented tutorial" you might notice a single aspect, but when you try copy it you realise the 'wow' factor is more holistic.
We haven't done everything perfectly but an example of a tutorial we did recently with some of these[0]
[0] https://codecapsules.io/docs/tutorials/build-a-docker-php-sq...
For tutorials specifically, use imperative mood for the instructions and headings.
Instead of, "Doing the thing," or, "How to do the thing," just say, "Do the thing."
I've noticed good tutorials using imperative mood, and my tutorials got much better when I started using it too.
In English, imperative mood is the best signal-to-noise you can get. It works well for tutorials because the target reader wants you to tell them what to do.
[1]: http://plainenglish.co.uk/how-to-write-in-plain-english.html
I enjoy to write technical things with jupyter.
- easy to get some command output beautifully - easy to organise text or any block - default theme looks nice with export html