6 lessons on technical writing you can learn from J.K. Rowling
I’m a big fan of the Harry Potter books and movies. I’m a bigger fan of the author - J.K. Rowling.
I have been watching a lot of her interviews and speeches lately and I was able to draw out 10 lessons on technical writing from her. Here they are:
1. Read as much as you can
You’ve got to read as much as you possibly can because that’s the best way to recognize good writing and to learn what makes bad writing… - J.K Rowling
You can’t get a sense of good technical writing if you don’t read technical articles as much as possible.
I read a ton of technical articles and documentations and this has helped shaped my writing style as I can see what I like and how a particular writer made me feel when I read their piece i.e did I become confused or knowledgeable?
2. Imitate your favourite technical writers
…You will possibly go through the phase where you will imitate your favourite writers and that’s okay… - J.K. Rowling
From reading as many technical articles as possible, you get to have a feel of what writing style you like and you easily understand. For me, that was Sarah Drasner’s.
I love the simplicity and humour in her writing and how she can make ideas simple. Even now when I write I still think of her influence on my work and if she will approve the article if she gets to proofread it.
So imitate your favourite writer in your early stage of technical writing and you will find yourself learning good habits and nuances on how best to communicate ideas. This should be enough to get your foot out the door but don’t stop there, find your style as well.
3. Write lots and lots of rubbish
…Resign yourself to writing lots and lots of rubbish… - J.K. Rowling
Now this one has to do with consistency and giving yourself to the iterative process. As software developers, we know that the building cycle of software never ends and that’s true for technical writing as well.
Write as much as possible because by doing so you are refining your craft of technical writing. Don’t expect your articles to hit a home run as you get started because it might even be your 10th or 100th article that will be amazing.
But you’ve got to keep on keeping on. Keep writing and learning from your writing. A good way to start is to write about the technologies you are learning about at the moment. Or even a tip or trick you found out recently.
Technical writing is like any skill and you get better at a skill by doing not just reading about it.
Don’t forget to share as your write!
4. Know everything about the subject matter
…I like reading a book where I have the sense that the authors knows everything… - J.K Rowling
Have you ever read an article or documentation where you feel the writer doesn’t know enough of what he/she is writing about? Or the writing is altogether not cohesive? I have and it’s not a good experience for readers.
As a reader, I like to feel that the writer knows everything about the subject matter and I can trust and have confidence in that knowledge.
You want to do your research deliberately and judiciously and spend time crafting every paragraph to the best of your ability to convey your intent with clarity.
Your readers should have the confidence that you know everything about what the article is about.
Also, don’t cram too much into a technical article. A great part of your job as a technical writer is to simplify the complexity of the technology you are writing on.
Again, know all there is to know about the subject matter you are writing on!
5. Add a human touch when possible
Most documentations and articles are so packed with technical jargon that leaves the readers more confused than they were when they sought the documentation or article.
Write as if you are writing for someone to learn from it and not just writing for writing’s sake. Keep it simple.
Simplify your grammar and technical jargon. Subtly add in humour when you can - folks love this as they feel that the writer is human and that makes what you are writing relatable.
6. Craft a catchy description
Your article description is what’s going to be read when you share it on social media and in search queries.
I think in your article description your potential reader decides whether your article is worth reading or not.
You do not want to give out too much in the description but you want to arouse their interest enough that they click on the link to the article.
The description of an article is like the cover of a book and we both know we all judge a book by its cover!
Conclusion
I had to reflect a lot about technical writing as I craft this article and I hope these tips will help me as well as you become stronger and better technical writers.