Hacker News new | past | comments | ask | show | jobs | submit login
Show HN: Writing for Software Developers (philipkiely.com)
267 points by philipkiely on May 12, 2020 | hide | past | favorite | 58 comments

Something, something, “Build your brand by writing.”

Something, something, “Communicating with words is as important as communicating with code in a team setting.”

But moving up Maslow’s Hierarchy, writing about ideas you want to personally explore (a’la pg) is exactly how you force yourself to think those ideas through. It’s valuable in its own right, whether people read them and shower you with the “three Ps” or not.

So write, and write often. Do not spend great amounts of time carefully choosing what yo write. Just write, and incorporate feedback into your work. Revise endlessly, much as one refactors software endlessly.

Do not write about things that don’t interest you just because you get more up-boats for “How to use Flibbitz in a managed K8s container with XML configuration,” unless Flibbitz personally interests you.

Write about what tickles your brain, and keep at it incessantly. What little (and it’s not much in the scale of things) success I’ve had writing essays and books can all be traced back to writing about things I personally care about.

My experience with low-barrier-to-entry fields like writing is, to make it to the top (which is what you want to do), you almost certainly have to do better, and have more specialized knowledge than, common-sense truisms like: work hard, be a good explainer, that sort of thing.

That's all low-barrier-to-entry knowledge. I'm not going to get much traction on Google with a tutorial like, "hello world" in Python. You have to improve on this low-value stuff to climb the ranks - which is what a book like this can offer.

I would respectfully say the advice you're offering here is a little too unfocused and low-yield, in the age of SEO.

Example: I'm a busy guy. I've written tutorials before, and it's pretty dispiriting to spend, say, 6+ hours writing something substantial (a realistic outlay for an article), only to see it wither away at the bottom of the Google rankings.

Similar example: build a no-name e-commerce store, watch it do nothing except cost you money.

So, you start to search for experts who know what they're doing - say, for e-commerce, SEO. They're not scam artists: they encourage you to write real, valuable content, and the good ones produce that themselves.

But they also say, you have to be more strategic than just like, low prices, placed next to paint-by-numbers articles. You have to search out keywords or areas that haven't been filled yet, and filled those.

And they often know counterintuitive things, that come from hard-won experience.

Example: for e-commerce, they say, you actually shouldn't just throw something up on the blog every week (a reasonable interpretation of the 'write often' advice). Instead, research a good area, then write a high-quality article, that you really invest in, over the course of several weeks. One such article can be worth 100+ low-quality articles which are basically just 'putting this up there to meet my quota for the week'. Internet traffic isn't linear - so it pays to have a strategy that acknowledges this, and builds off it.

That's one reason why I'm thinking of buying this book, since I think the non-obvious stuff is worth more than people commonly assume.

You’re talking about financial success, or something akin to that. I’m talking about personal development.

Writing is nothing like an ecommerce store to me. It is to you. Thus, my suggestions are not only irrelevant to you, they may be counterproductive for what you think is important.

They're more alike than you might think. Amazon seeks marketshare, and a writer seeks mindshare. Personal development, in that sense, runs on parallel tracks as financial success.

As an example: Who enjoys writing something that nobody reads? Who wants to write a tutorial for JavaScript, that's on page 1,000 of the Google search results, and only gets ready by 4 people?

They may diverge at a certain point: maybe you're OK with your writing on VM's to only get read by 3000 people, even if a comparable JavaScript tutorial would get read by 100000 people. But you'd still like for 3000 people to read your VM tutorial. Your writing has to reach an audience to make a difference, to effectively communicate.

On today's Internet, with no strategic thinking, no SEO whatsoever, there's a real risk that the VM article you spent 20 hours developing will only get read by 3 people. That's a depressing outcome, whether your goal is financial or personal.

To be clear, I feel like I have skin in the game here. I write partly for personal development, partly for financial success. But regardless, I still dislike it when I put a lot of work into something and nobody cares.

If you truly don't care if 0 people read what you write, we are definitely in different camps.

If you want your reading to be read - if you want mindshare - then you really do have to be mindful of this stuff.

Shrug. I am not Amazon, and I question that as an example. They sell a lot of terrible but popular stuff. If they were a writer, it’d be clickbait and advertising chum 24/7/365.

I have no interest in writing about “one weird trick to prove that arbitrary Collatz problems are undecidable.”

I like it better when my posts get read, but not because of mindshare, but because I get better feedback, which leads to better personal development.

But I would never write for mindshare at the expense of personal development. The two are in tension more often than may seem obvious.

For example, releasing early and often, even before a post is finished, means less mindshare, but can result in critical feedback earlier in the process, and helps me avoid “over-polishing a turd.”

We each are out for our own thing. You be you, I’ll be me. My advice reflects my goals, which I’m perfectly comfortable sharing. You have different goals, that’s fine too.

But your goals are not universal any more than mine are.

What are the three P's?

Haha, yeah! I'm having a blast looking at the search results...

Planet, People, Profit. People, process, product People, Process, Performance Management Personalization, Permanence, Pervasiveness Polydipsia, Polyuria, Polyphagia Product, Price, Place and Promotion Preserve / Prevent / Promote Prediction, Protection, Preparation Purpose, Process, Product Protect, Procreate, Provide. Protect, Provide, Profess Pee, Paper, Poo Purity, Patience, Perseverance Provision, Protection, Participation Presence, Promises, Power Of God Piracy, Portability, Profitability Presentation, Planning, Processing

But still no idea... OP, which is it?

Practice, Practice, and Practice, I think.

Power. Prestige. Pecuniarum.

Hey Philip,

really great to see you run with this! I know you mentioned to me that this repository[0] where I try to keep a short list of publishers that pay for this kind of writing was an early inspiration and I'm still hoping to grow that list a lot after June when I spend more time focusing on technical writing too.

As others have said, that's a really great looking list of interviewees. My only question is where this actually fits in to the rest of the book? It's not that clear from the Table of Contents. Could you comment on what percentage of the book is interviews, compared to writing advice?

[0] https://github.com/sixhobbits/technical-writing/blob/master/...

The table of contents outlines the book, which is about 30,000 of my words and 28,000 words of interview excerpts. Then, the appendix contains the full transcripts of all 11 interviews, 45,000 words (which does overlap with the interview excerpt word count from earlier).

Writing seems to be the single best thing you can do as a professional, in other areas as well. I know people who were hired because of a single Medium article that got a lot of traction (and made that person sort of a reference in the industry). What do you think about videos? I see lifestyle channels for devs and tech workers taking off but do you think there's a chance the same might happen for more technical channels as well? I find technical videos (like talks or tutorials) to be far more engaging than articles but I'm afraid I'm part of a very small minority.

Forced pace is a huge problem for videos. If you encounter a paragraph that you already know all about in an article, you can skip it. If you encounter a section of a video like that, it's harder to skip so I'll end up trying to sit through it, getting bored, then distracted, and then who knows what I'll miss.

The 'killer feature' of writing is the ability to self-pace. To me that makes them orders of magnitude more effective as a means of communicating ideas.

Written materials can also be used as reference much more easily. You can't ctr+f a video to look for the specific nugget of information you need.

I'm in the same boat. But I noticed a lot of my developer co-workers prefer video's. Especially the younger generation (I'm 41).

For self-pacing videos, this chrome plugin is VERY useful. You can watch videos at 2x, 2.2x, or any other increment of 0.1x: https://chrome.google.com/webstore/detail/video-speed-contro...

The killer feature of video is to bring in multiple pages of connected concepts and quickly tie them together, along with emotional emphasis.

It depends on how the video is structured. You should divide a video into sections and index them the same way you would with a book.

The lack of Ctrl-F too! Although maybe that’s a fixable problem with transcribed videos

Personal opinion on video v/s text channel. While watching a video, I have to follow a linear path, I can't skip much incase I miss some context. On the other hand, its easier to skim written content.

I have very little experience with making videos, but some of my interview subjects do! Chris on Code makes great technical videos and livestreams. There is a bit of information specific to video in the book, but I think the information about the planning, outlining, and editing of technical content would be helpful to people making video.

Scriptwriting is just a particular form of writing, so any process you've developed would work whether someone is writing technical tutorials for video or sonnet form. :D

Funny you should mention sonnets, Chapter 8 develops an example technical tutorial on generating sonnets by remixing Shakespeare's work.

That's what inspired me. :) I'm really curious to read this.

It might just be a problem with me, but I think that the level of articulation that a book can offer is way higher than what a video could. A book is written down, read, edited, and thoughtfully compiled, with the possibility of new editions coming out regularly. With a video this is less easy to do unless you want to keep re-recording.

Hi HN,

I have been working on Writing for Software Developers for six months and I'm so excited to finally launch it! I set myself the goal of launching before my (now virtual) university graduation and I'm proud to have hit that goal by six days.

Right now the book is 12 dollars off (launch pricing) and you can read chapter 1 for free at https://philipkiely.com/assets/files/wfsd_chapter1_sample.pd...

The book features interviews with 11 people, including @patio11 (Patrick McKenzie), who had the following to say about Hacker News. This quote is from Chapter 15, which covers promoting your work:

"At one point I was the number two user on Hacker News. I might have slipped down to number three...I think that people underrate Hacker News massively. I think there is a meme in the community that Hacker News threads are populated by toxic commenters and that it is a ceaselessly negative place such that the world would be better without Hacker News in it. I think unequivocally Hacker News is an extraordinary venue for value creation throughout the world, largely by bringing together technologists who would not have otherwise met each other. There are people who make lifelong relationships from that site. I met my former co-founders there; Thomas Ptacek is one of my best friends for life; and it feels extremely unlikely that I would have my current job but for Hacker News. I think you could say that for many people who are nowhere close to being quote-unquote on the leaderboard.

Hacker News helps disseminate ideas, like my ideas on sales and engineering career optimization and the body of practice that is dealing with venture funding, both from the startup side of the fence and from the investor side of the fence. These things would be difficult to get access to unless you had a high-quality social network that already had an expert about them in it. It is basically one step short of miraculous that you could find George Grellas, who is an expert Silicon Valley lawyer practicing for thirty years, and have George Grellas patiently walk you through the impacts of the changes in the independent contractor classification in the wake of Microsoft abuses in the 1990s. By the way, George Grellas was a practicing lawyer for Microsoft. That I could read that as a person who was newly an independent contractor working in central Japan in the late 2000s/early 2010s is one step short of miraculous.

I'll acknowledge that there are certain threads that are generally low quality, mostly things that are removed from the core interests of the technology industry. It's not a particularly great watering hole to talk about politics, for example. But, for the things it does well, Hacker News does them better than plausibly any place in the world...I wish more people who could get value out of Hacker News were active there."

Thanks to all eleven people who provided interviews for the book. Thank you for checking out my project! I'll be around to answer any questions.

I don't recall saying that grellas was a lawyer for Microsoft but I assume that might just be a transcription infelicity.

This is the comment which I was referring to: https://news.ycombinator.com/item?id=1137669

The existence of comments like this is one of the things I like most about this community, as described in the above quote. (Thanks all.)

Excellect choice interviewing Matt Levine. Can't wait for that.

thats awesome, congrats on launching!

as a fellow soon-to-be first time gumroad author - what was your tech stack for writing and publishing? i tried Ulysses and Scrivener and Leanpub and wasn't happy with any of them. looking to go from markdown to PDF/Epub/Mobi with good control over table of contents, footnotes, and linking between chapters.

i have a list of alternatives to explore.. just wondering what worked for you?

also - how did you mock up that book cover art on the landing page?

I wrote in Markdown as well. I turned that into a microsoft word doc that I formatted then created the PDF. I used pandoc to create the EPUB, then calibre to make the MOBI from the EPUB. I tried to use pandoc to make the PDF but it did not go well, word was surprisingly easy to use for that.

The cover art was created by a friend of mine from college. I used https://diybookcovers.com/3Dmockups/ to make the image on the landing page.

Congratulations, Philip :-)

Thank you, and thank you for the interview!

That’s a lot to unpack, I hope you have a blog or twitter link handy.

Keep it rolling!

Hey Philip,

Congrats on the launch of your new book. Will probably be checking out the first chapter after work.

As I've been hanging out more online, I've realized the increasing importance of writing. Even as a developer, writing seems to be a differentiating factor.

Other than your book, what are some other resources that you relied on in order to build up your skills as a writer? Or did you just rely on reading and emulating people's works.


Thanks for checking it out. One of the reasons I wrote this book was because there were so few resources for me starting out. I mostly relied on my experience as a journalist with my college's newspaper plus the training we got in CS classes on writing good documentation.

I didn't carefully read the whole article, scanned through it and read the comments. Sorry if I missed the answer.

Is this an intro / "how to" book about technical writting, or a book with a series of interviews with good writers. In the same genre as "Founders at work"?

Both! The first act is step-by-step on how to write technical tutorials. The second act is examples of that process. The third act is about the business of writing. All of that is a book that I wrote, but does rely heavily on block quotes from interview subjects, plus 30,000 of my own words :)

Then, the appendix contains all of the interview transcripts, totaling 45,000 words.

Thank you for clarifying

Keep writing!! I've personally started my journey into content creation as a software engineer just this year! To be more focused, I found a growing passion for Design Patterns and started writing my learning about them. Hope to share the same passion with you! Keep going pal! Would love to hear some tips from you! Here's my site, and hope it encourages you all!


This is so cool! I’ve just started myself (still putting together my blog). I really want to learn functional programming, maybe writing about it would be a good way to start on my journey too!

I'm definitely supporting you on this idea! I've learnt so much through "Learn as you teach" methodology. Do share your site once you have started it (:

Oh and personally, as a way to learn my frontend development skill, I also created my blog from scratch through a frontend framework! You can consider that as well

Wowowow! I've only read the FREE first chapter so far, but honestly, I'm pretty hooked. If the rest of the book is as useful and well-written as the first chapter (which I suspect it is) then the price is a steal. Following this book's advice in writing your own tech articles will earn you your money back from buying it within a couple of weeks.

Well done philipkiely!

The purchase link isn't working for me. I get a certificate error.

Edit: It appears that by connecting via my VPN, it gives me a certificate error when the link redirects via gum.co... goes away when I disable it.

Seems worrying...

I'm sorry you experienced difficulty purchasing it. If you are still having issues you can email me philip@kiely.xyz I'll see what I can do.

The website says "Earn money, make connections, and get noticed.The rates I earn from writing, usually $250 to $500 per article, add up." What are some ways to do that exactly?

I wanted to just automatically say booring! But then I clicked the link and I love it, thank you!

It’s short, simple and to the point. My personal holy trinity. See you around)

Downvotes? Love it)

Please don't break the site guidelines: https://news.ycombinator.com/newsguidelines.html.

Hey Philip, this is great. I'm curious, what tools did you use to produce the book?

I wrote in Markdown. I turned that into a microsoft word doc that I formatted then created the PDF. I used pandoc to create the EPUB, then calibre to make the MOBI from the EPUB. I tried to use pandoc to make the PDF but it did not go well, word was surprisingly easy to use for that. The cover art was created by a friend of mine from college. I used https://diybookcovers.com/3Dmockups/ to make the image on the landing page.

Amazing! Just purchased it. Thanks Phillip.

Question on the side: does anybody know of a good app that could "read" the epub for me? I feel like I could listen to these interviews while doing chores at home.

This app @Voice Aloud Reader is great for all kinds of docs. You can even long press paras in Chrome Android and in the long-press menu there'll be an option for Reading it Aloud.

epub,PDF etc. supported too, all details in app description.


Thanks for the support! I hope you enjoy it

"Throughout college, also I have sought physical engagement outside of martial arts, taking up climbing and lifting." [0]

Not to be harsh, but I wouldn't buy a book from someone writing about writing that writes awkward/grammatically incorrect sentences like the one above. Also your background doesn't "checkout". You're writing about writing for software engineers, but how long have you been a software engineer? 3 years? 5 years?

Again, my comments are a little harsh, but this has to stop with people filling the internet with useless content, making it harder and harder to find good content.

[0] (https://philipkiely.com/essays/black-belt-white-belt.html)

Thank you for taking the time to let me know how to improve my writing. Would you be so kind as to provide editorial feedback on other pages on my site? I look forward to incorporating your suggestions next time I revise my work.

One sentence and an arbitrary background check is not enough to determine that content is useless and not good in my opinion.

> this has to stop with people filling the internet with useless content

Good luck with that!

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact