In this episode, we dive into the role of communication as a developer, how clarity is driving impact and how to self publish as an independent writer. Join us, as we chat with Stephanie Morillo author of The Developers Guide to Content Creation about how to write better as developer and how writing can take you from good developer to great.
Developers encounter technical writing everywhere: product & API docs, manpages, tutorials & more. We know it matters but what is technical writing exactly? And how does it differ from other writing?
In this brief post, I define what technical writing is, provide examples of technical writing in software and beyond, and explore other skills technical writers must develop to create successful and effective documentation.
Writing is hard. Technical writing can be even harder. This piece by Sandy Maguire has lots of help in it:
Here’s the biggest thing to keep in mind: your reader doesn’t really care what you have to say. You get maybe four sentences to convince them that your essay is worth their time. If you haven’t made your case by then, you’ve probably lost them to the next tab they binge-opened.
For those out there that lead or contribute to a corporate engineering blog, Dan Luu interviewed folks at Cloudflare, Heap, and Segment, as well as folks at three different companies with “lame corporate engineering blogs” to get a sense of what makes them interesting or lame.
I’ve been comparing notes with people who run corporate engineering blogs and one thing that I think is curious is that it’s pretty common for my personal blog to get more traffic than the entire corp eng blog for a company with a nine to ten figure valuation and it’s not uncommon for my blog to get an order of magnitude more traffic.
In order to have a boring blog, the corporation has to actively stop engineers from putting interesting content out there. Unfortunately, it appears that the natural state of large corporations tends towards risk aversion and blocking people from writing, just in case it causes a legal or PR or other problem.
This week we’re talking about building technical courses! From video courses to written courses, we’ll give you our tips for building an effective and memorable course.
I’m giving away the four ways of generating ideas that I outline in the book. You can return to these sources over and over again when you need a new idea for your next developer blog post.
Stephanie Morillo (content strategist and previously editor-in-chief of DigitalOcean and GitHub’s company blogs) wrote a book titled The Developer’s Guide to Content Creation — it’s a book for developers who want to consistently and confidently generate new ideas and publish high-quality technical content.
We talked with Stephanie about why developers should be writing and sharing their ideas, crafting a mission statement for your blog and thoughts on personal brand, her 4 step recipe for generating content ideas, as well as promotional and syndication strategies to consider for your developer blog.
I’m not sure which is more interesting: the fact that Next.js is getting in to the static-site generation game or the fact that Notion is becoming popular enough amongst devs that people would use it as a back-end for their blog.
The Notion aspect, while interesting, comes with a big disclaimer:
since it is using a private API and experimental features, use at your own risk as these things could change at any moment.
I’ve been asked a few times about using algorithms in NetNewsWire to bring articles you wouldn’t otherwise have seen — from outside your feeds list — to your attention.
I’ve also been asked a similar question about using algorithms to bring articles — from inside your feeds list — to the top based on the likelihood that they’ll interest you.
I’m not going to do either.
Good for him.
This is what Twitter and Facebook are about — but it’s not right for NetNewsWire. The app puts you in control.
This is what I love about the spirit of RSS readers. More like this, please!
Zach Leatherman drummed up an amazingly hilarious way to use sentiment analysis on his website. I can’t even count how many ways I 💚 this.
You’re running out of good reasons to stay on Medium.
Mark Christian, being 💯% accurate:
Hello! This is my personal web site. It’s not much, but it’s mine. After nearly a decade of just barely existing, I’ve spent quite a bit of time in 2019 trying to breathe new life into it. At this point, I think just about everyone–but especially folks in the software engineering universe–should have a personal web site of their own. Let me tell you why.
This is like Markdown on steroids.
It supports diagrams, calendars, equations, and other features as extensions of Markdown syntax.
Switching away from Disqus reduced my page weight by over 10x and my network requests by over 6x. Disqus is bloated and sells your data - there are much better alternatives out there.
Disqus has been the de facto comment engine used for dev blogging (especially for SSGs) for years. I’m happy to learn there are less bloated and privacy-focused alternatives out there.
I recently moved my blog from Medium to a self-managed blog built with Gatsby in the open, then deployed on Netlify. After a few weeks of fiddling around, I feel like I’ve landed on something I’m mostly happy with.
This is a transition we are 💯 behind. Medium is becoming more reader-hostile all the time. Plus, wouldn’t you rather own your own content on a domain you have control over? Of course you would!
I’m logging this not because it’s super-useful in its current form (it is not). I’m logging this not because it’s a good example of a modern Swift app (it may be, I have no idea). Nope. I’m logging FeedCompass because it represents an idea that deserves more attention.
Independent websites, loosely stitched together via open protocols, are what make the web great.
Yeah, let’s do more of that.
In response to questions about how this change will affect compensation on Medium, Ev says:
It doesn’t affect compensation—assuming you mean for Partner Program. That’s determined by readership from paying members, which will still be counted (assuming they’re logged in). #
In response to questions about the state and future of Medium, Ev says:
Generally it’s 📈. Lots of growth and good stuff happening. I have been meaning to give an update. Thanks for the nudge. #
This tweet from Shannon Ashley states she made $8,069.96 writing on Medium in February 2019 and has the screenshot to prove it. She even wrote “What It’s Like To Be All-In On Medium” but you have to be a paying member to read it.
This post from Dan Abramov about why he moved off Medium summarizes both why we’re no longer linking to Medium and why we’ve never put our content there.
Some of my Medium articles unexpectedly got behind a paywall. I’m not sure what happened and whether that’s still the case. But I didn’t do it myself, and that caused a blow to my confidence in Medium as a platform. I respect their need to monetize, but it felt wrong when done retroactively.
Sam Soffes Jekyll’s a little differently.
This iteration is built on top of Jekyll, a static site generator written in Ruby.
Since I write my posts differently than Jekyll expects, I had to write several plugins to make things work correctly. You might wonder why I don’t just write my posts the way Jekyll wants instead of doing all of this work. I want to keep the details of my blogging engine separate from my content.
I’d love to hear from you about your blogging stack in the discussion below. Like Sam, I’m also using Jekyll hosted on Netlify, but I’m new to his plugins.
Stephanie knows her stuff when it comes to creating developer-focused content. If you’re in devrel (or want your thoughts/opinions to impact your fellow devs), this is a must-read. Don’t make these mistakes!
Ghost fans: bookmark this site for the next time you want a fresh coat of paint for your blog. 🎨
One of the tradeoffs of using a static site generator like Jekyll is not having scheduled posts. Sure you can add a date in the future, but static means exactly that, there’s no dynamic part to find and compare dates and times. Without complex hacks, I hadn’t found an easy way to do scheduled posts with Jekyll. That is, until now.
Stephanie Morillo drops some wisdom she gained running the Digital Ocean blog for the past year:
Teams need buy in from the engineering org, a primary owner for all things blog related, a regular publishing cadence, ongoing conversations, flexibility, cross-functional communication, and open dialogue with readers to get the most out of their blog efforts.
Getting buy-in can be the hardest part. I have a hard time convincing myself to blog, let alone other people.
Parker Moore joined the show to talk with Adam about blogging for hackers with Jekyll and GitHub Pages.