What do you look for in a good developer article/tutorial?

#discuss #writing

I've been sitting on an article (a Google Assistant tutorial) for a while, trying to groom it to be great! However I've been kind of stuck in a paralysis afraid of it not being perfect.

I know at some point I will have to just hit publish and go for it, but I figured I'd ask the community...What are some good things to have in an article/tutorial that make the whole thing a joy to read and learn from?

Top comments (4)

Aaroh Mankad • Feb 9 '18

I personally love at least a couple code samples that are as close to copy and paste as possible.

This isn't because I don't like to learn the content, but because I want to see a tangible result as soon as I can. You can then dissect that code/example to show how everything works, build on top of it, etc.

Steven Washington • Feb 9 '18

That's always cool! Especially something like CodePen (which I just found out that dev.to has a liquid tag for!) is something that can get you in the thick of it immediately.

aurel kurtula • Feb 10 '18

I don't think you can achieve perfection, and asking people to give you random tips would not work - as you can see.

The problem is that you are asking for tips that you already know. You are not an author, you are an author and a reader, hence you know all the "tips" that we know. In fact you know more tips because as you are interested to get the perfect tutorial, you might have started reading existing tutorials with pen and paper in your hands taking notes on their structure.

As I wrote in a similar question, publish your tutorial then ask feedback.

I'm new at writing, but for what it's worth this is how I approach writing tutorials

I have played with the tech I'm basing my tutorial on.
I roughly know step one of the tutorial and I know the end (step one get nails and hammer, conclusion, you have a bird cage)
I know my target audience. I imagine I am in a room with a group of people and I am teaching them. They are all as good as me, they simply haven't had time or interest to play with the thing I'm covering in the tutorial.
If I get a tingling that someone in the group is lost, I explain the problem better. For example in my last tutorial I created a middleware, whilst it was clear, by example, how it works, I knew that one of my ideal people would appreciate an easy example, so I added it in.
I write at least two drafts and I read it few times and get the computer to read it for me - when I listen to what I wrote I pick all sorts of problems.
I start the project afresh as if I was reading the article for the first time. I copy and paste code and if I end up with the desired outcome, my job is done.

I've been a member of quora for years. You could say I was an avid reader. I read so many writers, to me they were amazing writers, and they said that they do not write for likes, shares or followers. They write because they had to. I didn't understand it! I tried writing in quora and every time, at least for many years, I'd have my fingers crossed hoping I'll get upvotes :)

Only when I started writing tutorials here, I have started to understand what they were saying. Some said they write multiple drafts which I thought they must have some screws loose, other's said they'd read a question in the morning and think about it all day!

Now, now that I found my real interest, writing web tutorials, I do all those things, without trying.

At the moment, I'm trying to find my own style, and along the way experiment with my writing. But the core aim - I already broke it down in the bullet points - is to satisfy my imaginary audience, which clearly exists out there.

Further, for your own personal development, you should just publish, and you can revisit the topic again in the future.