Show HN: Writing for Software Developers
philipkiely.com
philipkiely.com
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.
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.
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.
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.
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.
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?
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 '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.
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.
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.)
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?
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.
Keep it rolling!
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.
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"?
Then, the appendix contains all of the interview transcripts, totaling 45,000 words.
https://blog.phuaxueyong.com/post/2020-05-03-3-more-cloud-de...
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
Well done philipkiely!
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...
It’s short, simple and to the point. My personal holy trinity. See you around)
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.
epub,PDF etc. supported too, all details in app description.
https://play.google.com/store/apps/details?id=com.hyperionic...
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)
Good luck with that!