Ask HN: How to Visually Design Tutorials?

https://news.ycombinator.com/item?id=33212593

by elbear • 4 years ago

18 9 4 years ago

news.ycombinator.com

I like to write articles about technology or to create tutorials.

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.

taubek• 4 years ago

Take a loot at Write the Docs site. They have great resources. https://www.writethedocs.org/guide/index.html

eimrine• 4 years ago

IMO visual representation of information is not a king, text is. Illustrations are great when I am trying to figure out something completely unknown. If you will produce some Really Great Illustrations, next thing you will be thinking about is to add just a little bit of work and to produce a video.

sixhobbits• 4 years ago

It's a lot of small things that add up:

- 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...

atoav• 4 years ago

First structure the thoughts, then structure the text. Think about which thought should get how much room and how natural the transitions between the thoughts feel. If you have to explain a side thought maybe give it its own paragraph, or even some sort of "Good to know"-box.

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.

bitlax• 4 years ago

I don't know if this works for your format but I thought these were great back in the day:

https://nodeschool.io/#workshoppers

dontdieych• 4 years ago

Not exact answer for your Q.

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

rjmill• 4 years ago

The plain English campaign [1] has some great advice and tips (especially about using bullet points.)

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

Mezzie• 4 years ago

Who are you writing them for? That's going to determine some of these decisions, speaking from an instructional design perspective.

elbear• 4 years ago

My audience is usually made up of programmers.

Ask HN: How to Visually Design Tutorials?

Related Stories