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)
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.
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.
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'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.
sometimes I like a background story but not a few times when I'm in hurry.