Recommendation of the book "Writing for Software Developers"
I know it has been a long time since my last email, so in case you forgot, this is the Writing for Developers newsletter. You subscribed to it at some point in the past to get advice about writing. I am still on a pause from the newsletter, but I wanted to break this hiatus to recommend a book about writing that I stumbled upon in the interwebs.
The book is "Writing for Software Developers", and its author is Philip Kiely.
His website is very clear (as you would expect) about the value of the book, take a look: philipkiely.com/wfsd
Philip is a programmer, author, and entrepreneur. He launched "Writing for Software Developers" and sold well over 500 copies in the first week, which happened to be just last week. He told me that the discounted launching price lasts only until today (Monday, May 18th, in case you are considering buying it).
"Writing for Software Developers" is about the craft and the business of creating technical content, with a focus on writing programming tutorials. The book also features interviews with 11 experts from in and around the world of technical content.
I don't know Philip, I have no affiliation with him, and the similarity of the name is just because we talk about the same topic to the same audience. Precisely the reason why I thought it would be a good idea to talk about the book here when I learned about it on Hacker News. I won't earn any commission or any kind of reward if any of you happen to buy the book. I am just sharing a resource that I believe might be useful.
I contacted Philip on Twitter, and he was kind enough to answer some questions that I had about the book. The book has a primary focus on guiding the reader through the process of writing a technical article for a large audience. I went through the book, and I can tell that it adds value even if you are not interested in becoming a professional writer.
Here is the short Q&A that I had with Philip. It might help you decide if the book can be a useful resource to you.
Q: Your book is focused on writing technical articles, but I usually talk about writing in the context of day-to-day communication in this newsletter. What advice can you extract from your book that also applies to writing emails or Slack messages to communicate more effectively with coworkers?
A: I wrote the book with a focus on creating technical tutorials and selling them to clients for three reasons:
Writing a 2,000-word article is a great first challenge for aspiring technical content creators.
There is a large amount of demand for great technical tutorials from publishers, who are willing to pay 200-500 dollars per post.
My experience is mostly from writing these kinds of technical tutorials for clients.
However, the book is called "Writing for Software Developers" because the skills that are required for this kind of writing transfer readily to other formats. Writing technical content is all about clearly communicating complex information to a niche audience. Writing an email or Slack message means that you have a very narrow audience, often only one person, who you hopefully have worked with before and understand very well. This means that you can deploy all of the skills that you use for writing for a public audience in a targeted, and thus effective, manner.
Q: Now, moving to yet another context. What advice also applies to writing for an internal audience? Like documentation, readme files, memos.
A: In a technical tutorial, I walk readers through the process of creating and understanding a programmed artifact. This exact structure, applied to documentation, whether internal or external, is extremely effective. One of the best technical tutorials that I have ever read is Django's introductory tutorial (https://docs.djangoproject.com/en/3.0/intro/tutorial01/) which is part of the framework's official documentation and sets a standard that takes a lot of effort to meet every time I write about Django. Great internal documentation is written exactly the same as public-facing documentation, especially in the case of set-up guides and introductions to projects or frameworks, as that material is often useful for onboarding new people to a team.
Q: More than writing, your book is a complete step-by-step guide on how to become a professional technical writer. Including sections on pricing, monetization models, promotion. What are some of the considerations a software developer should have before deciding if they want to invest in becoming a professional technical writer?
A: There are three things people should check before creating technical content for clients:
Are you bound by any agreements with employers or other clients to not write about certain topics or not freelance for certain companies?
Are you able to create your article without infringing on anyone else's intellectual property?
Given that you also receive some public recognition and the satisfaction of helping others, are you prepared to spend ten hours crafting a great technical tutorial for rates between 200 and 500 dollars?
If the answers to the above questions are, in order, (yes, no, yes), sit down and start writing. Question three is, of course, not applicable if you are writing for your employer or your own site rather than an external client. (I'm not a lawyer or registered advisor, this is commentary, not legal, business, or tax advice).
