DEV Community

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

Collapse
 
aurelkurtula profile image
aurel kurtula

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.