How some good corporate engineering blogs are written(danluu.com)
danluu.com
How some good corporate engineering blogs are written
https://danluu.com/corp-eng-blogs/
99 comments
Dan, having been that exact same bottleneck it's common for many.
And echo everything your said. In terms of getting something out the door as soon as you do that you've diminished the impact of the post. It's similar to quality engineering you ship it when it is ready, not because you said it'd take a week and you spent a week on it. Most engineers hate artificial marketing deadlines, being able to work on a post to get it into a good state can be equally as unclear in terms of timing as engineering.
I've found that a dedicated mentoring process, similar to your buddy system can work well. As you're growing the people that are able to review/drive content having them follow along as I review posts and provide feedback helps for them to internalize some of the steps. In my experience after shadowing for about 5 posts they're able to start guide someone else with still some need for support and final reviews.
A final note, as someone that has written a lot of content I can crank out a post in anywhere from a day to an hour. For someone that has an interest in a topic you shouldn't expect the same output (time wise) as someone that does this more frequently, a quality blog post for someone not used to the process can spend multiple days up to a week in total on it. This comes down over time and with practice, so you shouldn't assume it's always that high, but it does take repetition.
Finally, everyone has interesting technical things to talk about. Anytime an internal email is sent to engineering@ about some interesting tip, how some problem was solved, or a guide to how to accomplish something it's a great candidate for a post.
And echo everything your said. In terms of getting something out the door as soon as you do that you've diminished the impact of the post. It's similar to quality engineering you ship it when it is ready, not because you said it'd take a week and you spent a week on it. Most engineers hate artificial marketing deadlines, being able to work on a post to get it into a good state can be equally as unclear in terms of timing as engineering.
I've found that a dedicated mentoring process, similar to your buddy system can work well. As you're growing the people that are able to review/drive content having them follow along as I review posts and provide feedback helps for them to internalize some of the steps. In my experience after shadowing for about 5 posts they're able to start guide someone else with still some need for support and final reviews.
A final note, as someone that has written a lot of content I can crank out a post in anywhere from a day to an hour. For someone that has an interest in a topic you shouldn't expect the same output (time wise) as someone that does this more frequently, a quality blog post for someone not used to the process can spend multiple days up to a week in total on it. This comes down over time and with practice, so you shouldn't assume it's always that high, but it does take repetition.
Finally, everyone has interesting technical things to talk about. Anytime an internal email is sent to engineering@ about some interesting tip, how some problem was solved, or a guide to how to accomplish something it's a great candidate for a post.
:wave: hi Craig!
I'll also note that we asked Craig for eng blog advice way back in Jan 2017, and he was very helpful. :)
I'll also note that we asked Craig for eng blog advice way back in Jan 2017, and he was very helpful. :)
> A good blog won't just happen if you get out of the way.
true, but if you get in the way, you have a lifeless/corporate-feeling blog, which is (subjectively) worse.
as someone who has worked in the blogging trenches, i can say that overzealous/overconservative processes can really stifle blogging flow and the primary alternative you're competing against is the engineer writing for their personal blog, which they know has long term career value as well. usually not all participants in the review chain are equally bought in to growing the blog and you eventually get your best writers self selecting out if you aren't careful
i do like the buddy system you propose, that seems like a nice solve!
what are your thoughts on having dedicated content writers - like technical writers or developer advocates - working on/owning the blog, vs "all engineers are explicitly encouraged to blog"?
true, but if you get in the way, you have a lifeless/corporate-feeling blog, which is (subjectively) worse.
as someone who has worked in the blogging trenches, i can say that overzealous/overconservative processes can really stifle blogging flow and the primary alternative you're competing against is the engineer writing for their personal blog, which they know has long term career value as well. usually not all participants in the review chain are equally bought in to growing the blog and you eventually get your best writers self selecting out if you aren't careful
i do like the buddy system you propose, that seems like a nice solve!
what are your thoughts on having dedicated content writers - like technical writers or developer advocates - working on/owning the blog, vs "all engineers are explicitly encouraged to blog"?
> what are your thoughts on having dedicated content writers - like technical writers or developer advocates - working on/owning the blog, vs "all engineers are explicitly encouraged to blog"?
I like this, and I think a good developer relations person who is prolific, sufficiently technical, and can get the tone right can be very valuable for building up a company's visibility. It's a good way to take 80% of the work of writing a post off the relevant engineer's plate and also produce great posts, because the person writing them is a professional writer.
We're small enough right now that we can do well enough with some ad hoc stuff, e.g. periodic slack posts to shake the tree. But this is something we discuss every now and then and the timing will be right at some point, as we scale.
It's easier to justify the cost of a full-time employee if your buyers are also primarily engineers. For someone like Stripe or Twilio, an active eng blog doubles as marketing.
I like this, and I think a good developer relations person who is prolific, sufficiently technical, and can get the tone right can be very valuable for building up a company's visibility. It's a good way to take 80% of the work of writing a post off the relevant engineer's plate and also produce great posts, because the person writing them is a professional writer.
We're small enough right now that we can do well enough with some ad hoc stuff, e.g. periodic slack posts to shake the tree. But this is something we discuss every now and then and the timing will be right at some point, as we scale.
It's easier to justify the cost of a full-time employee if your buyers are also primarily engineers. For someone like Stripe or Twilio, an active eng blog doubles as marketing.
This concern applies to every process that a CxO inserts themself into.
You have 200 employees and only one person you trust to publish communications to the public? Why not put a little trust in your teammates?
You have 200 employees and only one person you trust to publish communications to the public? Why not put a little trust in your teammates?
To be clear we're talking about the state of the world around two years ago. I'm not a bottleneck for this anymore. :)
Also, this is a bit of an uncharitable read. The calculus at the time wasn't about trust per se, and more about the fact that the relationship between quality of blog content and the content's reach is nonlinear. That means it's worth taking the time to get it right, even if the people best suited to make that happen aren't super available, because the difference between getting on the front page of HN vs not is multiple orders of magnitude. (But I think we get the best of both worlds now.)
Also, this is a bit of an uncharitable read. The calculus at the time wasn't about trust per se, and more about the fact that the relationship between quality of blog content and the content's reach is nonlinear. That means it's worth taking the time to get it right, even if the people best suited to make that happen aren't super available, because the difference between getting on the front page of HN vs not is multiple orders of magnitude. (But I think we get the best of both worlds now.)
Personally, I feel the main part where I face the most difficulty in writing blog posts (for companies), are illustrations which adhere to the branding guidelines/style of the company. I feel these custom illustrations are something that makes the blog stand out and the content easy to consume (attractive?) for a general reader.
Even if there are no direct instructions to follow the design principles/themes of the company, it kind of makes sense that there are some underlying design principles that all the tech blogs are adhering to (in terms of videos, animations, illustrations, code snippets).
I know about tools like [1] but they are fairly basic (afaik) in terms of visuals.
For instance, look at the amount of work in creating illustrations for [2], it seems they had someone assigned from the design team to help with these. Another example is in the blog post [3] linked in the original post.
[1]: https://www.websequencediagrams.com/, https://mermaid-js.github.io/mermaid/#/ [2]: https://www.toptal.com/ruby-on-rails/decoupling-rails-compon... [3]: https://blog.cloudflare.com/content/images/2019/06/leak2-2.p...
Even if there are no direct instructions to follow the design principles/themes of the company, it kind of makes sense that there are some underlying design principles that all the tech blogs are adhering to (in terms of videos, animations, illustrations, code snippets).
I know about tools like [1] but they are fairly basic (afaik) in terms of visuals.
For instance, look at the amount of work in creating illustrations for [2], it seems they had someone assigned from the design team to help with these. Another example is in the blog post [3] linked in the original post.
[1]: https://www.websequencediagrams.com/, https://mermaid-js.github.io/mermaid/#/ [2]: https://www.toptal.com/ruby-on-rails/decoupling-rails-compon... [3]: https://blog.cloudflare.com/content/images/2019/06/leak2-2.p...
We are really lucky at Cloudflare having a just amazing designer https://twitter.com/kkblinder who can create an illustration or diagram so fast I still don't know how she does it.
Could of years ago I wrote a blog post explaining Spectre and Meltdown (aimed at the relative layperson): https://blog.cloudflare.com/meltdown-spectre-non-technical/ She did the illustrations based on a really vague explanation by me of what was needed. I think they really made the piece.
More recently, she helped me with state machine images in this piece: https://blog.cloudflare.com/details-of-the-cloudflare-outage... Here she did them in the style of an old CS paper.
Could of years ago I wrote a blog post explaining Spectre and Meltdown (aimed at the relative layperson): https://blog.cloudflare.com/meltdown-spectre-non-technical/ She did the illustrations based on a really vague explanation by me of what was needed. I think they really made the piece.
More recently, she helped me with state machine images in this piece: https://blog.cloudflare.com/details-of-the-cloudflare-outage... Here she did them in the style of an old CS paper.
One of the best pieces of feedback I got at Heroku was don't stress too much on it being perfect. In fact you can make it rough as if drawn on a napkin so it intentionally isn't visually polished and it accomplishes its goal. I in fact started doing some of this way back at Heroku 9 years ago and the approach worked well. Now I've leveled that up with an iPad and paper.
Yes, there are places that have designers and they're a great resource, but don't let that be a blocker. If a company has a designer that can be dedicated and support such awesome. If not just try something and see what works, then keep using it.
Edit: An example of very crude/napkin style drawing - http://www.craigkerstiens.com/2011/11/07/how-heroku-works-ma...
Yes, there are places that have designers and they're a great resource, but don't let that be a blocker. If a company has a designer that can be dedicated and support such awesome. If not just try something and see what works, then keep using it.
Edit: An example of very crude/napkin style drawing - http://www.craigkerstiens.com/2011/11/07/how-heroku-works-ma...
Now that you mention it, Ben Thompson uses this hand drawn art style at Stratechery[1] - it seems like something that is easy and fast enough to do with one of the countless iPad drawing apps and an Apple Pencil.
[1]: https://stratechery.com/
[1]: https://stratechery.com/
I'd say a consistent style or pattern is important, but illustrations, specifically, are not required. Check out the Harvard Law Review. It contains thousands of articles without an image.
https://harvardlawreview.org/
https://harvardlawreview.org/
I think part of the issue is some places (where I am too) use medium for their blog and medium requires an image. Not sure if other blogging platforms do the same though.
> Medium requires an image
Is that why so many medium posts have an irrelevant and distracting image that has to be scrolled past? What an idiotic requirement.
Medium claims to have awesome presentation but I always read their articles in “reader” mode to get rid of the pointless distractions.
Is that why so many medium posts have an irrelevant and distracting image that has to be scrolled past? What an idiotic requirement.
Medium claims to have awesome presentation but I always read their articles in “reader” mode to get rid of the pointless distractions.
It's not a Medium requirement. I've published plenty of articles without images, and the site just adds a blank box as a placeholder.
However, a lot of 'become popular on Medium' guides recommend you use an image, and an image likely looks better than a blank box does, hence all the images.
However, a lot of 'become popular on Medium' guides recommend you use an image, and an image likely looks better than a blank box does, hence all the images.
I didn't know about this requirement either. I'm reminded of what Jakob Nielsen has written on the subject:
https://www.nngroup.com/articles/photos-as-web-content/
> Summary: Users pay close attention to photos and other images that contain relevant information but ignore fluffy pictures used to "jazz up" web pages.
https://www.nngroup.com/articles/photos-as-web-content/
> Summary: Users pay close attention to photos and other images that contain relevant information but ignore fluffy pictures used to "jazz up" web pages.
I always would want a company blog to be under a company domain, which Medium doesn't allow any more. For various reasons: from a branding/search perspective, for flexibility (e.g. being able to embed whatever you want for visualizations, examples, ...) and to be able to move it without breaking all the links (e.g. when you finally decide Mediums constant popups are a bad look for your professional representation)
[deleted]
Know your audience. Illustrations can certainly be helpful to a general audience but they won’t save poorly organized content. The written content should flow well enough to stand on its own.
If you are writing a blog where corporate branding is associated then commandeer a graphic designer from your employer. They are going to be more in tune with the company’s legally approved branding guide and likely to produce better quality visual products in less time.
If you are writing a blog where corporate branding is associated then commandeer a graphic designer from your employer. They are going to be more in tune with the company’s legally approved branding guide and likely to produce better quality visual products in less time.
The images at the second link are so nice! curiously enough, I wasn't seeing them because they were being blocked by Pi-hole (with default block lists)...
I definitely become more attracted to companies with high quality blog posts on things I'm interested in. The right blog is a really big signal that I'd be interested in the work at the company.
Besides picking the next company, great blog posts can be a real help in sanity checking the work that's happening in our team. I've noticed even senior engineers treating good blog posts from big companies as "See, we're not crazy".
Right now I'm operating in the data science platform space at my company, and have been reading a lot more company blogs than usual. Wayfair is a company I now know of after an engineer I really respect shared on Twitter "Bayesian Product Ranking at Wayfair"[1].
Lyft, on the other hand, disappointed me with "How Lyft Designs the Machine Learning Software Engineering Interview"[2]. That post sounds like it could have been victim to what Dan notes as:
> Approval/editing process mainly de-risks posts, removes references to specifics, makes posts vaguer and less interesting to engineers
1. https://tech.wayfair.com/data-science/2020/01/bayesian-produ...
2. https://eng.lyft.com/how-lyft-designs-the-machine-learning-s...
Besides picking the next company, great blog posts can be a real help in sanity checking the work that's happening in our team. I've noticed even senior engineers treating good blog posts from big companies as "See, we're not crazy".
Right now I'm operating in the data science platform space at my company, and have been reading a lot more company blogs than usual. Wayfair is a company I now know of after an engineer I really respect shared on Twitter "Bayesian Product Ranking at Wayfair"[1].
Lyft, on the other hand, disappointed me with "How Lyft Designs the Machine Learning Software Engineering Interview"[2]. That post sounds like it could have been victim to what Dan notes as:
> Approval/editing process mainly de-risks posts, removes references to specifics, makes posts vaguer and less interesting to engineers
1. https://tech.wayfair.com/data-science/2020/01/bayesian-produ...
2. https://eng.lyft.com/how-lyft-designs-the-machine-learning-s...
Wayfair's tech stack is kind of a dumpster fire -> https://www.teamblind.com/post/Technical-incompetence-at-Way...
I would read through their engineering blogs with a critical eye.
I would read through their engineering blogs with a critical eye.
> Lyft, on the other hand, disappointed me
Lyft has put out some fantastic blog posts around their work on Envoy. Check out the posts by Matt Klein: https://medium.com/@mattklein123
Lyft has put out some fantastic blog posts around their work on Envoy. Check out the posts by Matt Klein: https://medium.com/@mattklein123
I was the eng blog lead at Lyft until recently, and ran it for years. We have a really lightweight process: just needs to be approved by your director, and copy-edited by someone on the blog team. Process usually only takes a week or two. You should probably check out the other posts on the blog.
We aim our posts towards a number of audiences. Our posts related to our interview process are to let candidates know what to expect when they're coming in for specific interview types. We actually get very high traffic to those posts, and we've gotten strongly positive feedback from candidates about those posts, so we've written them for a number of positions.
We also have posts oriented towards working with non-engineering teams, mentoring, engineering processes (like writing tech specs), and other things that aren't only technical deep-dives, because we believe in diversity of content.
We aim our posts towards a number of audiences. Our posts related to our interview process are to let candidates know what to expect when they're coming in for specific interview types. We actually get very high traffic to those posts, and we've gotten strongly positive feedback from candidates about those posts, so we've written them for a number of positions.
We also have posts oriented towards working with non-engineering teams, mentoring, engineering processes (like writing tech specs), and other things that aren't only technical deep-dives, because we believe in diversity of content.
Fair enough. So not true that an editing process watered down that particular blog post. I still maintain that that blog post is too wishy-washy, and others agree[1].
I've read other posts on Lyft's blog that are awesome. I did not intend to say that Lyft's blog is bad in general.
1. https://news.ycombinator.com/item?id=21409066
I've read other posts on Lyft's blog that are awesome. I did not intend to say that Lyft's blog is bad in general.
1. https://news.ycombinator.com/item?id=21409066
This post is totally accurate. I am a corporate blogger, and when I started at this company, we had a ridiculous approval process involving legal. Now, we just don't do that process, and focus on getting the engineering stuff right and doing absolutely no other content: engineering only, no marketing crap. By removing legal approvals, we went from publishing once a week to publishing once a day, and our hits have doubled in a year. Approval processes that extend past engineering are evil.
I think this doesn't account for what is, in my experience, the most common reason why engineering blogs fail: they have the wrong objective altogether.
In a former life, back when printed magazines were still a thing, I used to do some (pretty bad) tech journalism, so every time $crt_employer wanted to run, or expand their blog, I ended up going to meetings (I now do that professionally as well, actually -- it helps keep those programming-related brain cells sane). The vast majority of posts (and blogs) that I've seen were awful not because of a tortuous approval process or lack of high-level support. They were awful because communicating substantial, serious engineering information was not the main point. Or one of the main points. Or a point at all, really. It was usually just an excuse to push out some marketing and "establish a presence", and management felt that involving technical people writing on technical subject would lend that effort the kind of credibility that ads don't have.
This had repercussions over the whole publishing chain, and these efforts were doomed from the beginning. Topic selection was inadequate (topics were selected primarily so that they'd have the right "ring" to product/marketing/business development managers, rather than so that they'd be interesting for a technical audience). Editing was done with the wrong objectives and targeted the wrong metrics, and was often based solely on input from non-technical people who didn't understand what a technical audience wanted. Then this article -- on a topic that wasn't really interesting for a technical audience, and not really written for a technical audience -- was promoted mostly for a technical audience. Since the people who were doing the promotion were, inherently, in non-technical position, and they mostly consisted of a boring tech article with a mini sales pitch attached at the end, everyone ended up seeing them as marketing fluff.
It doesn't help that our industry is still stuck in this world where "technical" and "non-technical" is a very strict dichotomy, where technical people are basically like a 2020 Mr. Spock and non-technical people can barely type on a computer. That hasn't been then case in more than ten years. A lot of people who are seen as "non-technical" -- people in sales, marketing, or in management positions -- have grown up with computers. Lots of people in decision-making positions used to hold a technical position at one point. The kind of depth that a non-technical, but not tech-illiterate audience appreciates can be very surprising.
In a former life, back when printed magazines were still a thing, I used to do some (pretty bad) tech journalism, so every time $crt_employer wanted to run, or expand their blog, I ended up going to meetings (I now do that professionally as well, actually -- it helps keep those programming-related brain cells sane). The vast majority of posts (and blogs) that I've seen were awful not because of a tortuous approval process or lack of high-level support. They were awful because communicating substantial, serious engineering information was not the main point. Or one of the main points. Or a point at all, really. It was usually just an excuse to push out some marketing and "establish a presence", and management felt that involving technical people writing on technical subject would lend that effort the kind of credibility that ads don't have.
This had repercussions over the whole publishing chain, and these efforts were doomed from the beginning. Topic selection was inadequate (topics were selected primarily so that they'd have the right "ring" to product/marketing/business development managers, rather than so that they'd be interesting for a technical audience). Editing was done with the wrong objectives and targeted the wrong metrics, and was often based solely on input from non-technical people who didn't understand what a technical audience wanted. Then this article -- on a topic that wasn't really interesting for a technical audience, and not really written for a technical audience -- was promoted mostly for a technical audience. Since the people who were doing the promotion were, inherently, in non-technical position, and they mostly consisted of a boring tech article with a mini sales pitch attached at the end, everyone ended up seeing them as marketing fluff.
It doesn't help that our industry is still stuck in this world where "technical" and "non-technical" is a very strict dichotomy, where technical people are basically like a 2020 Mr. Spock and non-technical people can barely type on a computer. That hasn't been then case in more than ten years. A lot of people who are seen as "non-technical" -- people in sales, marketing, or in management positions -- have grown up with computers. Lots of people in decision-making positions used to hold a technical position at one point. The kind of depth that a non-technical, but not tech-illiterate audience appreciates can be very surprising.
> people in sales, marketing, or in management positions -- have grown up with computers.
This doesn't mean anything. Have you watched some 15-22 year olds interact with computers lately? (I'm 23, for reference). They don't hunt and peck on the keyboard in stereotypical fashion but they're just as clueless for anything besides basic interactions. They -are- essentially tech illiterate once they step outside of google sheets, etc, or the web browser in general.
I'm tired of hearing people say "digital native" like it means anything with regards to tech literacy. We're going to have another generation come in and take power that has zero idea of how computers function. At least we understood this and factored this in about the last generation- now we just assume the new generation knows things because they grew up using apps.
If anything, the new generation is more illiterate on average, but with better mechanical facilities and understanding of typical modern UX for apps.
This doesn't mean anything. Have you watched some 15-22 year olds interact with computers lately? (I'm 23, for reference). They don't hunt and peck on the keyboard in stereotypical fashion but they're just as clueless for anything besides basic interactions. They -are- essentially tech illiterate once they step outside of google sheets, etc, or the web browser in general.
I'm tired of hearing people say "digital native" like it means anything with regards to tech literacy. We're going to have another generation come in and take power that has zero idea of how computers function. At least we understood this and factored this in about the last generation- now we just assume the new generation knows things because they grew up using apps.
If anything, the new generation is more illiterate on average, but with better mechanical facilities and understanding of typical modern UX for apps.
Your definition of “tech literacy” is way skewed. These people are able to use technology to do what they need: they’re tech literate. They can talk with their friends over the internet, create and layout documents, print posters, do research; they’re fluent across multiple devices and platforms; many of them interact with some sort of computer for hours each day. What more do you want them to do? (I’m in the age range you specified, by the way.)
My definition involves understanding how computers work to a decent degree outside of basic app usage.
Being mechanically efficient at using computers (and by this, I mean being efficient at using carefully- designed apps) does not count in my eyes. If any problem occurs, or if one has to do anything outside of the basic app flow, then people go blank.
I operate a car daily, does that make me car literate? I understand mechanically how to operate a car, but if anything out of the ordinary occurs I have no idea what to do. Except to call someone who is actually car literate to fix the problem. Usage does not correlate with literacy.
When a problem occurs, I've seen many people not even read the error messages or display basic critical thinking ability. I can't call this tech literacy.
> They can talk with their friends over the internet, create and layout documents, print posters, do research
This is a testament to programmers and UX designers making easy to use applications, not people being "tech literate".
Being mechanically efficient at using computers (and by this, I mean being efficient at using carefully- designed apps) does not count in my eyes. If any problem occurs, or if one has to do anything outside of the basic app flow, then people go blank.
I operate a car daily, does that make me car literate? I understand mechanically how to operate a car, but if anything out of the ordinary occurs I have no idea what to do. Except to call someone who is actually car literate to fix the problem. Usage does not correlate with literacy.
When a problem occurs, I've seen many people not even read the error messages or display basic critical thinking ability. I can't call this tech literacy.
> They can talk with their friends over the internet, create and layout documents, print posters, do research
This is a testament to programmers and UX designers making easy to use applications, not people being "tech literate".
> They -are- essentially tech illiterate once they step outside of google sheets, etc, or the web browser in general.
25 years ago there were people who were essentially tech illiterate as soon as they were put in front of a computer, not just when they stepped outside of Google sheets or the web browser in general.
You think having grown up with computers, in a world where technology is easily-available and part of pop culture means nothing, but it has been years since I've last had to explain a grown-up that some computers are faster than others, that something which is available on paper can be made easily made available on a computer (scanning, photography etc.), what a server is, or that a website can become unavailable if too many people access it.
It used to be that writing for a non-technical audience entailed unthinkable effort for seemingly trivial things. Not just explaining technical terms. We had lists of words we had to be especially careful with because they also had non-technical meanings, and if someone wasn't aware of that, they could get the wrong idea. That list included words like "server", "mouse" and "window", and I've personally seen grown-up people standing behind imposing desks who got really confused upon hearing these words without the proper context.
Eight year-olds who just learned how to read and write can pick up a word processor with way less effort than eight year-olds (and non-technical fifty year-olds) could twenty years ago. They understand, for example, how scrolling works. Teaching people how to use a word processor used to entail explaining things such as "you can keep typing once you're at the end of the page". You needed to say that explicitly because the interface didn't seem to have any way for you to get another sheet of paper once you filled one up. People would write things on a page until they got near the bottom, then proceeded to stare quizzically at the screen wondering how they could get another one -- because that's exactly what they did in real life.
I'm not saying that people who grew up with computers don't need to be told what TCP is and what a load balancer does. But they do have an intuitive understanding of things that a non-technical audience from twenty years ago didn't have. Including super basic things that you take for granted now, but it used to be that you couldn't -- that things from the Internet don't show up on your computer instantly, that how quickly they do depends on the quality of a connection, that computers need to be given explicit instructions each time (i.e. they'll always ask if you want to save your work before quitting -- they'll never figure out that you always say yes).
25 years ago there were people who were essentially tech illiterate as soon as they were put in front of a computer, not just when they stepped outside of Google sheets or the web browser in general.
You think having grown up with computers, in a world where technology is easily-available and part of pop culture means nothing, but it has been years since I've last had to explain a grown-up that some computers are faster than others, that something which is available on paper can be made easily made available on a computer (scanning, photography etc.), what a server is, or that a website can become unavailable if too many people access it.
It used to be that writing for a non-technical audience entailed unthinkable effort for seemingly trivial things. Not just explaining technical terms. We had lists of words we had to be especially careful with because they also had non-technical meanings, and if someone wasn't aware of that, they could get the wrong idea. That list included words like "server", "mouse" and "window", and I've personally seen grown-up people standing behind imposing desks who got really confused upon hearing these words without the proper context.
Eight year-olds who just learned how to read and write can pick up a word processor with way less effort than eight year-olds (and non-technical fifty year-olds) could twenty years ago. They understand, for example, how scrolling works. Teaching people how to use a word processor used to entail explaining things such as "you can keep typing once you're at the end of the page". You needed to say that explicitly because the interface didn't seem to have any way for you to get another sheet of paper once you filled one up. People would write things on a page until they got near the bottom, then proceeded to stare quizzically at the screen wondering how they could get another one -- because that's exactly what they did in real life.
I'm not saying that people who grew up with computers don't need to be told what TCP is and what a load balancer does. But they do have an intuitive understanding of things that a non-technical audience from twenty years ago didn't have. Including super basic things that you take for granted now, but it used to be that you couldn't -- that things from the Internet don't show up on your computer instantly, that how quickly they do depends on the quality of a connection, that computers need to be given explicit instructions each time (i.e. they'll always ask if you want to save your work before quitting -- they'll never figure out that you always say yes).
I'm not arguing that people aren't better at using computers than the previous generation. I'm arguing they aren't necessarily more -literate-.
I'm saying that intuitively understanding UX is different than understanding how a computer works.
I don't trust either generation to be competent enough to enact legislation regarding computers.
I'm saying that intuitively understanding UX is different than understanding how a computer works.
I don't trust either generation to be competent enough to enact legislation regarding computers.
I think this is exactly what the post is about.
If you leave it to the marketing people you'll get buzzword fluff that provides no value or interest to anyone.
If you leave it to the engineers to write about interesting things, and get the approval process out of the way then you might put up something of interest to engineers.
If you leave it to the marketing people you'll get buzzword fluff that provides no value or interest to anyone.
If you leave it to the engineers to write about interesting things, and get the approval process out of the way then you might put up something of interest to engineers.
> If you leave it to the engineers to write about interesting things, and get the approval process out of the way then you might put up something of interest to engineers.
True, but there's also a good chance that you will get something that provides no marketing value, or employer branding, or sales value, or any kind of value whatsoever. Sure, you get an interesting blog post, but why should a company pay its engineers to do that?
IMHO, good corporate blogs happen at the intersection between marketing and engineering. If the process is skewed too much towards one end, what you get is rarely worth it. There are exceptions (there are plenty of people doing marketing, or engineering, whose vision exceeds their own department) but they're very few. Most companies can't afford them, and those that can often fail to attract them.
True, but there's also a good chance that you will get something that provides no marketing value, or employer branding, or sales value, or any kind of value whatsoever. Sure, you get an interesting blog post, but why should a company pay its engineers to do that?
IMHO, good corporate blogs happen at the intersection between marketing and engineering. If the process is skewed too much towards one end, what you get is rarely worth it. There are exceptions (there are plenty of people doing marketing, or engineering, whose vision exceeds their own department) but they're very few. Most companies can't afford them, and those that can often fail to attract them.
> It doesn't help that our industry is still stuck in this world where "technical" and "non-technical" is a very strict dichotomy, where technical people are basically like a 2020 Mr. Spock and non-technical people can barely type on a computer.
It can still feel that way, though, especially if you have any intersection of cutting-edge software or hardcore engineering with corporate bureaucracy. It's really a question of roles-in-context not holistic identity. If you have corporate managers and project people spending a lot of time in meetings talking about the "ABC initiative" to each other without a single one of them even having taken the time to walk through a basic "Hello World" tutorial for the ABC itself, you are dealing with "non-technical" people.
It can still feel that way, though, especially if you have any intersection of cutting-edge software or hardcore engineering with corporate bureaucracy. It's really a question of roles-in-context not holistic identity. If you have corporate managers and project people spending a lot of time in meetings talking about the "ABC initiative" to each other without a single one of them even having taken the time to walk through a basic "Hello World" tutorial for the ABC itself, you are dealing with "non-technical" people.
Yeah, many engineering blogs fail because of content reasons, not organisational ones. In many of the smaller places I worked at there weren't any institutional obstacles to posting content to the blogs. It was a matter of not caring much about the blog or writing the wrong content (stuff that isn't helpful or interesting).
For a successful corporate blog (engineering or otherwise), writing blog articles needs to be a foundational part of the company culture, the different teams must work together to create the best/most useful content possible, and there must be a schedule beyond 'whenever we feel like it'.
For a successful corporate blog (engineering or otherwise), writing blog articles needs to be a foundational part of the company culture, the different teams must work together to create the best/most useful content possible, and there must be a schedule beyond 'whenever we feel like it'.
true to have a blog post to strike a balance between technical and non-technical is tedious but have to say this blog post I shared recently has hit a sweet spot https://medium.com/dsaid-govtech/using-robust-optimization-a...
The question on how to utilize social networks and platforms like blogs and connected to that Twitter etc is a recurring theme of all my employers so far. And it's an unsolved problem. The core question is who should create a text (or pretty much anything not resulting in a product), when and why? Obviously it would be a red flag if a company expects an employee to invest private time into something like this. But how much time is supposed to be dedicated? I have been blogging on data stuff for a while and a sound, well-written and non-trivial article takes longer to write than a work day. And that is an investment that most managers shy away from and instead compromise on quality or just ditch the idea. Writing shallow articles for a while will be demotivating, boring and not worthwhile in the long run.
I really respect companies that have well-written engineering blogs that go in-depth into their technical problems - Figma comes to mind here, for example.
For a small team/company, what are some good tips or resources on how to start an engineering blog? We've worked on many interesting challenges and I know the team would have a lot of insights to share, but it can be difficult to find and justify the time that writing a good article takes, and it's not something that everyone is necessarily interested in doing either.
I'm curious about the mention of Cloudflare's culture of "internal blogging". That seems to me like it could be a first step in that direction.
For a small team/company, what are some good tips or resources on how to start an engineering blog? We've worked on many interesting challenges and I know the team would have a lot of insights to share, but it can be difficult to find and justify the time that writing a good article takes, and it's not something that everyone is necessarily interested in doing either.
I'm curious about the mention of Cloudflare's culture of "internal blogging". That seems to me like it could be a first step in that direction.
We use Confluence for all sorts of stuff and there's a blog category. It's full of stuff. Some of it would make a great public blog (in fact, one cool investigation is getting turned into a public blog right now). Some of it is so internal and full of details that it wouldn't do well publicly but is good for others inside the company to read (and a good way of having a memory of how we did something).
At a previous company (30-40 employees) the main thing was having a blog setup somewhere that engineers could post to - clearly distinguished from the main product blog. Actually getting engineers to write up blog posts was a separate problem. Besides me there were only a handful, even when it was made clear that it could be about a very small topic. A few hundred words is plenty.
Not CF, but my employer has a list for emails like that, where people might report on things they did, things that didn't work, ... Which sometimes is only of internal relevance, sometimes about things we can't share publicly, but sometimes also prompts "this could be a blog post interesting to other people"
My experience at Pivotal (now VMware) echoes Dan Luu's point: the less friction to publish, the more posts on the engineering blog [0].
Our current set-up is simple: clone a repo, create a blog post (in Markdown) from a template, and when you're ready to publish, commit & push to the master branch. We put a lot of effort into making the process simple for engineers.
However, before that process was put in place, it was much more burdensome. I remember in 2014 I had written a blog post and it needed to go through Marketing: Branding was important, and formatting was a challenge. Also, I encountered feedback unrelated to engineering content: "You need a call to action," said the person in charge. I was baffled: "If they've found my post, it's because they're trying to fix a particular problem--they've already had their call to action." The process was discouraging, and I didn't write a blog post for a long time afterwards.
[0] http://engineering.pivotal.io/
Our current set-up is simple: clone a repo, create a blog post (in Markdown) from a template, and when you're ready to publish, commit & push to the master branch. We put a lot of effort into making the process simple for engineers.
However, before that process was put in place, it was much more burdensome. I remember in 2014 I had written a blog post and it needed to go through Marketing: Branding was important, and formatting was a challenge. Also, I encountered feedback unrelated to engineering content: "You need a call to action," said the person in charge. I was baffled: "If they've found my post, it's because they're trying to fix a particular problem--they've already had their call to action." The process was discouraging, and I didn't write a blog post for a long time afterwards.
[0] http://engineering.pivotal.io/
While the concept of blogs for engineers by engineers is great and has many benefits I think author is understating the risks.
There is a non-trivial overlap between "look at this cutting edge cool stuff we're doing" and the company's strategic edge over competitors.
These types of posts get dissected by the competition & a small slip up can give away a lot of clues.
There is a non-trivial overlap between "look at this cutting edge cool stuff we're doing" and the company's strategic edge over competitors.
These types of posts get dissected by the competition & a small slip up can give away a lot of clues.
To be honest, I don't think giving away information about your strategic edge matters that much. What does matter is the culture of a company. If you're hustling, you'll create extra new edges big and small all the time. If it's a big edge, the general outline will be good enough to tip off your competitor without you talking about it. As the saying goes, execution matters a lot more than ideas.
You can share your knowledge, which quickly turns you in a gathering point for interesting knowledge. This makes interesting stuff, good employees and new customers come to you begging for attention, which is a much bigger strategic edge.
See for example the story of Tom Wilson's videocard at Mike Abrash's https://www.phatcode.net/res/224/files/html/ch64/64-01.html - a minimal hint which turned out to be wrong was enough inspiration for a better product.
On the other hand, imagine Dan Luu's example company that takes a year to approve a blog post. If your culture is that bad, even discussing if accepting a mountain of money laying on the street no strings attached is acceptable will take a few months. Show them your edge, and assuming they see it as actually valuable instead of extra work, it will still take a year of bureacratics before they start implementing it.
See also Rudyard Kipling:
They copied all they could follow but they couldn't copy my mind so I left them sweating and stealing a year and a half behind.
You can share your knowledge, which quickly turns you in a gathering point for interesting knowledge. This makes interesting stuff, good employees and new customers come to you begging for attention, which is a much bigger strategic edge.
See for example the story of Tom Wilson's videocard at Mike Abrash's https://www.phatcode.net/res/224/files/html/ch64/64-01.html - a minimal hint which turned out to be wrong was enough inspiration for a better product.
On the other hand, imagine Dan Luu's example company that takes a year to approve a blog post. If your culture is that bad, even discussing if accepting a mountain of money laying on the street no strings attached is acceptable will take a few months. Show them your edge, and assuming they see it as actually valuable instead of extra work, it will still take a year of bureacratics before they start implementing it.
See also Rudyard Kipling:
They copied all they could follow but they couldn't copy my mind so I left them sweating and stealing a year and a half behind.
> There is a non-trivial overlap between "look at this cutting edge cool stuff we're doing" and the company's strategic edge over competitors.
I don't really agree. I think the more you write about what you are doing the more you attract really good people and that's the strategic edge on competitors.
I don't really agree. I think the more you write about what you are doing the more you attract really good people and that's the strategic edge on competitors.
I think the bigger risk is you write a blog about some "cool stuff" you are doing and it's actually not cool, it's dumb and obsolete and people who might have been thinking about working at your company go apply to Microsoft instead. There's abundant examples of "How we handled a billion queries per year with only 1000 servers" out there. It's the risk that you don't know how you really compare to your peers.
Personally, the only "technical blog" I want to see from a company is papers accepted by OSDI, ISCA, VDLB, etc.
Personally, the only "technical blog" I want to see from a company is papers accepted by OSDI, ISCA, VDLB, etc.
Sometimes you can drill into things that wont give anyone an edge but will help out many people due to lack of documentation. There's so many solutions I find for web stuff after googling around and reading through code after code only to come up with my own unique variation.
I think there are a lot of things people can post about that are not core to the business value. Of course any IP or trade secrets should be kept off the blog, which is, I assume, why the CTO typically reviews posts at the "good blogging" companies Dan mentioned.
There is also liability as a risk. At least for big companies. There is no money in sueing a startup, but big companies get constantly trialed. Especially, if they work in security/safety/mission-critical field.
The level of expertise required to write a blog post is way above average. The imposter syndrome stops me from writing one.
Almost inevitably you will get comments about how your approach is bad or simply invalid.
Almost inevitably you will get comments about how your approach is bad or simply invalid.
I've had this conversation with a lot of folks, you don't have to be an expert to write a blog post. Some of the most common and valuable ones were how I learned x or y. There are a lot more beginners out there than experts.
> Almost inevitably you will get comments about how your approach is bad or simply invalid.
Have you considered that this is probably just the anxiety talking? In my experience people don't go out of their way to be mean. Unless you specifically choose to be controversial, the worst case is people will be indifferent and just won't share/upvote.
Have you considered that this is probably just the anxiety talking? In my experience people don't go out of their way to be mean. Unless you specifically choose to be controversial, the worst case is people will be indifferent and just won't share/upvote.
Fast path is essential for corp blog posts. Reduce friction. Don’t even think about using your standard corporate release approval process, it’s unsuitable. As for design, I’m a minimalist. This is an engineering blog so it should be like sitting in an engineering meeting. The chairs and mugs are corporate colours but the diagrams can be _very basic_ while still being clear. It’s a balance.
> my blog helps me with job searching and it helps companies hire. But I only need one job, so more exposure, at best, gets me a slightly better job
I feel the same way about open source in my case. I already have, say, 6+ repos with quite a few stars, high quality and lots of installs. I keep doing OSS because I like publishing the tools I make and other people using them, but it's definitely past the point where there is a ROI with hiring.
Recently I got `react-test` and I'm building it, but I decided to ask for help from beginner programmers. I think it can get to a very nice place within the OSS community, and I don't mind sharing the credit with other contributors. We even published a bunch of detailed issues asking for help but I haven't found many people who are interested yet: https://dev.to/fpresencia/contributing-to-js-react-open-sour...
I feel the same way about open source in my case. I already have, say, 6+ repos with quite a few stars, high quality and lots of installs. I keep doing OSS because I like publishing the tools I make and other people using them, but it's definitely past the point where there is a ROI with hiring.
Recently I got `react-test` and I'm building it, but I decided to ask for help from beginner programmers. I think it can get to a very nice place within the OSS community, and I don't mind sharing the credit with other contributors. We even published a bunch of detailed issues asking for help but I haven't found many people who are interested yet: https://dev.to/fpresencia/contributing-to-js-react-open-sour...
The irony of the linked blog having no justified text, larger headlines--instead of just using bold regular text--nor reasonable margins is staggering. I find it very annoying to read.
Anyone have thoughts on companies that don't include authors' names in blog posts? My (big N) employer anonymizes our technical blog posts.
This reads as if "blog" is a metaphor for "product". I'm guessing that blog process is a pretty good indicator of development strategy. Stale bland blogs predict stale bland engineering.
I really like the segment.com blog.
It's not just about the content, but the typography, the style, illustrations... I don't know why but I'm more and more sensitive with the general reading experience.
It's not just about the content, but the typography, the style, illustrations... I don't know why but I'm more and more sensitive with the general reading experience.
I wanted to try it, but their RSS/ATOM feed support is broken. The feed[1] currently 404's with a single emoji[2]. No feed support is a non-starter for me.
Question for you since you presumably read their blog: Do you follow a bunch of blogs/news sources? If so, how do you do it without using feeds?
[1]: https://segment.com/blog/atom.xml
[2]: https://emojipedia.org/police-car-light/
Question for you since you presumably read their blog: Do you follow a bunch of blogs/news sources? If so, how do you do it without using feeds?
[1]: https://segment.com/blog/atom.xml
[2]: https://emojipedia.org/police-car-light/
> I really like the segment.com blog.
I've heard good things about it, but uMatrix blocks their entire site. A quick Googling indicates that they are some sort of analytics/tracking firm.
Do they serve their tools off of the same domain as they content, or is uMatrix being overeager?
I've heard good things about it, but uMatrix blocks their entire site. A quick Googling indicates that they are some sort of analytics/tracking firm.
Do they serve their tools off of the same domain as they content, or is uMatrix being overeager?
I explored the business idea of "engineering blog in a box" and talked to a couple of companies about it. The idea was that, just like a drip campaign for customers has value, so does a drip campaign for engineers. You provide good content, an easy way to subscribe, and periodic calls to action (around a role) and you'll get conversions (aka hires).
Didn't go anywhere, but it seems that engineering blogs are an unoptimized recruiting channel. If anyone here wants to chat more about this idea, my email is in my profile.
Didn't go anywhere, but it seems that engineering blogs are an unoptimized recruiting channel. If anyone here wants to chat more about this idea, my email is in my profile.
I like the idea, but I think the reason it didn't stick were related to the bell curve of engineering competence in the wild. And probably the tendency of companies where IT isn't the main game but an enabler not wanting to expose the wild stuff going on to sustain the facade.
If every company blogged about how the magic happens then you'd get a couple of side effects. 1. It'd be a coup for the open source security researchers. 2. Companies would lie, or only blog about there flagship stuff. 3. Companies who are honest would probably scare away engineers with blog posts like, How we support our 30 year old credit card system running on Mainframe hardware we source from ebay. 4. Companies would use this to value signal to each other to open a new front of competitive advantage to the detriment of everyone else. Remember when K8 was just for large web scale companies.
If every company blogged about how the magic happens then you'd get a couple of side effects. 1. It'd be a coup for the open source security researchers. 2. Companies would lie, or only blog about there flagship stuff. 3. Companies who are honest would probably scare away engineers with blog posts like, How we support our 30 year old credit card system running on Mainframe hardware we source from ebay. 4. Companies would use this to value signal to each other to open a new front of competitive advantage to the detriment of everyone else. Remember when K8 was just for large web scale companies.
I think the harder sell is that you can't get immediate ROI (it's a months long play).
And that the optimal customer (fast growing tech company) for this type of service quickly grows out of it and wants to insource it (or blogging gets tangled in PR/markcom).
I don't think anyone blogs about all the warts of their systems (not even Cloudflare etc). Everyone wants to put their best foot forward.
And that the optimal customer (fast growing tech company) for this type of service quickly grows out of it and wants to insource it (or blogging gets tangled in PR/markcom).
I don't think anyone blogs about all the warts of their systems (not even Cloudflare etc). Everyone wants to put their best foot forward.
> It'd be a coup for the open source security researchers.
How so?
How so?
>One person at a company with a compelling blog noted that a downside of having only one approver and/or one primary approver is that if that person is busy, it can takes weeks to get posts approved.
One way around this would be to have 14 stakeholders arranged so that any individual can approve the post. That would do as much to speed it up as a 14-person unanimous/veto system would do to slow it down.
One way around this would be to have 14 stakeholders arranged so that any individual can approve the post. That would do as much to speed it up as a 14-person unanimous/veto system would do to slow it down.
One thing the company I currently work for has done is to use our "corporate blog" as a directory for technical employee's personal blogs. Many of our tech team members write blog posts on their own time about technical problems they're particularly interested in. Having our corporate blog (https://codeshare.getfreebird.com/) redirect to their personal blog allows our company to highlight our team's ability and provide interesting content, while the authors get a signal boost from having their content referenced from the company's technical blog.
We're a small technical team so I'm not sure how well this scales, but it's worked out well for us so far.
We're a small technical team so I'm not sure how well this scales, but it's worked out well for us so far.
What is the purpose of engineering blogs? Is it only to attract engineers to work for you?
Well, they can actually be helpful. I've found a lot of good info on company blogs from engineers about embedded programming, electronics, and other topics.
You can also think of it as marketing for engineer types who are usually immune to formal forms of marketing. Managers don't care about details, they want to see $ numbers. Engineer types want gory details. So your engineering blog can help market your products to engineers. Just look at intels documentation pages vs their actual intel.com site. intel.com is marketing 101 eyesore.
An example would be a blog from a semiconductor company making analog circuits. Think Bob Pease types. They'll talk about a specific problem or circuit, go into the bloody details, math, schematics, charts, graphs, etc. Then toss you a product from their portfolio that can solve the problem.
You can also think of it as marketing for engineer types who are usually immune to formal forms of marketing. Managers don't care about details, they want to see $ numbers. Engineer types want gory details. So your engineering blog can help market your products to engineers. Just look at intels documentation pages vs their actual intel.com site. intel.com is marketing 101 eyesore.
An example would be a blog from a semiconductor company making analog circuits. Think Bob Pease types. They'll talk about a specific problem or circuit, go into the bloody details, math, schematics, charts, graphs, etc. Then toss you a product from their portfolio that can solve the problem.
It also provides exposure and recognition for the engineers who write content for them, or who have their technologies features in the blog posts.
I love to go through the corporate engineering blogs and learn/understand the type of technical problems they are trying to solve and enhance my skills. Good for learning about the company for tech interviewing too. But there is no simple way to search through all of them for a specific term (like kubernetes for eg). To solve this problem, I have designed http://techblogz.co. It currently has 10k entries from different corporate engineering blogs.
Would love to hear your feedback on it.
Thanks
Would love to hear your feedback on it.
Thanks
I have many ideas for blog posts but i cannot execute them myself.
I am solo founder and i am not great at writing English technical docs. Well i havent write a technical blog post in Greek either, so i am not sure if English is the only reason i havent written a single blog post.
Should i find a buddy for this? Proofreading? But could he provide the quality i want?
I think i will implement an excellent blog platform in Jekyll and github pages. Maybe mak it open source, this is the closest i can get to blogging.
I am solo founder and i am not great at writing English technical docs. Well i havent write a technical blog post in Greek either, so i am not sure if English is the only reason i havent written a single blog post.
Should i find a buddy for this? Proofreading? But could he provide the quality i want?
I think i will implement an excellent blog platform in Jekyll and github pages. Maybe mak it open source, this is the closest i can get to blogging.
Heh. I just got a company-wide email this morning, about an internal engineering blog post. The first one ever! This could be cool? Maybe?
So I did the needful, loaded the images in the email in Outlook, and was greeted with a headline about caring for others, and why I should put MY face mask on first, before helping someone else.
Uh... Not the engaging technical content I was hoping for.
So I've got one data point for how NOT to do it, if someone's keeping a list.
So I did the needful, loaded the images in the email in Outlook, and was greeted with a headline about caring for others, and why I should put MY face mask on first, before helping someone else.
Uh... Not the engaging technical content I was hoping for.
So I've got one data point for how NOT to do it, if someone's keeping a list.
My company [1] writes technical blog posts as a service [2]. We mostly work with Bay Area startups. Some key observations and learnings:
- Many companies have tried to create engineering blogs, but you'd never know because the first post was so unpleasant to create that the whole effort got called off.
- If a company does manage to publish a first post, the experience is often so personally traumatic to the engineer that they never try again and/or tell their team members to avoid the process. This is especially true when PR/Comms insists on reviewing posts. (Legal review typically goes more smoothly.)
- Coming up with ideas for posts is WAY easier said than done. Nobody, engineers included, likes staring at a blank page. A significant part of our work is refining ideas and creating outlines.
- Lest you thought otherwise, company engineering blogs are almost always justified as candidate lead gen. Posts are frequently used by recruiters in outreach emails. When a post and email are well written, response rates can easily double—effectively doubling the candidate pool for a growing team. (This assumes that engineers aren't applying to jobs unprompted, which is true for about 80% of startups in the Bay Area.)
- In our research with job seekers, we found that when senior engineers research a company, they seek the company's engineering blog before they seek the careers page, let alone a job description. This is probably obvious to folks here, but in the recruiting world this blows everyone's mind.
- Technical blog posts are expensive whether you DIY or work with someone like us. A detailed post, let's say 1500 words, can easily consume 25 hours of time from everyone involved. 50 hours isn't rare. And this is when the process works well. (Our value prop: we shift time from engineers to our writers.) Here's the process we've found works best. Everything here happens in Google Docs.
1. One of our writers, all former journalists, sits down with an engineer who has an idea for a post. In a 1 hour conversation, they work together to refine the idea and create a bare-bones outline. Assuming you're doing this yourself, my point is that pairing is helpful. This conversation gets recorded and transcribed by a transcription service. (4 hours total time)
2. The writer reviews the transcript and fleshes out an outline. They note locations for graphics and code snippets. The engineer then reviews the outline and leaves comments. (4–6 hours total time)
3. The writer creates a complete first draft, with assistance from 1–2 editors on our team. They leave space for graphics/code for the engineer to add on their own. (8–10 hours)
4. The engineer brings in 1–3 other engineers to review the post. The team adds illustrations and/or code. More comments/feedback. (6+ hours)
5. Our writer incorporates feedback. An editor on our team proofreads the post for clarity, grammar, etc. (2–4 hours)
6. Legal and/or team leaders review the post. (2+ hours)
7. Whomever runs the blog puts everything in the CMS and hits publish. (1 hour)
End of the day, we've ideally consumed fewer than 10 engineer hours. The rest is on us—anywhere from 15–30 hours.
Feel free to email me directly about any of this :) [email protected]
[1] https://www.jobportraits.com/, [2] https://www.jobportraits.com/services/tech-blog-post-subscri...
- Many companies have tried to create engineering blogs, but you'd never know because the first post was so unpleasant to create that the whole effort got called off.
- If a company does manage to publish a first post, the experience is often so personally traumatic to the engineer that they never try again and/or tell their team members to avoid the process. This is especially true when PR/Comms insists on reviewing posts. (Legal review typically goes more smoothly.)
- Coming up with ideas for posts is WAY easier said than done. Nobody, engineers included, likes staring at a blank page. A significant part of our work is refining ideas and creating outlines.
- Lest you thought otherwise, company engineering blogs are almost always justified as candidate lead gen. Posts are frequently used by recruiters in outreach emails. When a post and email are well written, response rates can easily double—effectively doubling the candidate pool for a growing team. (This assumes that engineers aren't applying to jobs unprompted, which is true for about 80% of startups in the Bay Area.)
- In our research with job seekers, we found that when senior engineers research a company, they seek the company's engineering blog before they seek the careers page, let alone a job description. This is probably obvious to folks here, but in the recruiting world this blows everyone's mind.
- Technical blog posts are expensive whether you DIY or work with someone like us. A detailed post, let's say 1500 words, can easily consume 25 hours of time from everyone involved. 50 hours isn't rare. And this is when the process works well. (Our value prop: we shift time from engineers to our writers.) Here's the process we've found works best. Everything here happens in Google Docs.
1. One of our writers, all former journalists, sits down with an engineer who has an idea for a post. In a 1 hour conversation, they work together to refine the idea and create a bare-bones outline. Assuming you're doing this yourself, my point is that pairing is helpful. This conversation gets recorded and transcribed by a transcription service. (4 hours total time)
2. The writer reviews the transcript and fleshes out an outline. They note locations for graphics and code snippets. The engineer then reviews the outline and leaves comments. (4–6 hours total time)
3. The writer creates a complete first draft, with assistance from 1–2 editors on our team. They leave space for graphics/code for the engineer to add on their own. (8–10 hours)
4. The engineer brings in 1–3 other engineers to review the post. The team adds illustrations and/or code. More comments/feedback. (6+ hours)
5. Our writer incorporates feedback. An editor on our team proofreads the post for clarity, grammar, etc. (2–4 hours)
6. Legal and/or team leaders review the post. (2+ hours)
7. Whomever runs the blog puts everything in the CMS and hits publish. (1 hour)
End of the day, we've ideally consumed fewer than 10 engineer hours. The rest is on us—anywhere from 15–30 hours.
Feel free to email me directly about any of this :) [email protected]
[1] https://www.jobportraits.com/, [2] https://www.jobportraits.com/services/tech-blog-post-subscri...
> Technical blog posts are expensive whether you DIY or work with someone like us. A detailed post, let's say 1500 words, can easily consume 25 hours of time from everyone involved.
I feel like this glosses over the fundamental question. You've just written a 500 word comment about your company's business; it's grammatical, well-formatted, communicates both overall scope and low level details, even has an introduction and conclusion. But I'm sure your team didn't spend 25/3 ~= 8 hours on it, and I'm pretty confident you skipped the majority of the listed steps. Why does scaling up by a factor of 3 require such a huge paradigm shift?
I feel like this glosses over the fundamental question. You've just written a 500 word comment about your company's business; it's grammatical, well-formatted, communicates both overall scope and low level details, even has an introduction and conclusion. But I'm sure your team didn't spend 25/3 ~= 8 hours on it, and I'm pretty confident you skipped the majority of the listed steps. Why does scaling up by a factor of 3 require such a huge paradigm shift?
Good points all around! For the record, if you (or someone on your team) can write great posts quickly solo, that's awesome and I'd never dissuade it. But a lot needs to go right for that to be possible. For an individual to pull it off, IMO you need to meet these criteria:
- You yourself are doing something technically interesting
- You know enough about the project and/or topic to write on behalf of your team members and company. (Because posts on company blogs are perceived to represent everyone.)
- You need to be a competent writer. Sub-skills matter, too: editing, proofreading, creating visuals, and more. This simply takes practice, especially if you expect to move fast.
- It helps if you're a native english speaker, which many engineers are not.
- If you're truly doing it all yourself, you need to know your way around whatever CMS your company uses. Most engineers don't.
- You need to know enough to anticipate the repercussions. Love them or hate them, this is what Legal/PR/Comms are for.
If all this is true, yes, an individual can write a great post in a single day.
To answer your question directly, I was able to write my main comment quickly because:
- I was responding to something. I wasn't writing from scratch. Hot takes are easy ;)
- I'm a cofounder. AKA: I'm comfortable writing on behalf of my company. It's actually part of my job.
- HN comments are lower stakes than a blog post. No long-term SEO impact, for example.
- I've been doing this for 10+ years. And my 500 word comment still took me 90 min to write and edit.
- Yup, I'm a native english speaker.
- Probably some other factors I'm blind to at this point.
- You yourself are doing something technically interesting
- You know enough about the project and/or topic to write on behalf of your team members and company. (Because posts on company blogs are perceived to represent everyone.)
- You need to be a competent writer. Sub-skills matter, too: editing, proofreading, creating visuals, and more. This simply takes practice, especially if you expect to move fast.
- It helps if you're a native english speaker, which many engineers are not.
- If you're truly doing it all yourself, you need to know your way around whatever CMS your company uses. Most engineers don't.
- You need to know enough to anticipate the repercussions. Love them or hate them, this is what Legal/PR/Comms are for.
If all this is true, yes, an individual can write a great post in a single day.
To answer your question directly, I was able to write my main comment quickly because:
- I was responding to something. I wasn't writing from scratch. Hot takes are easy ;)
- I'm a cofounder. AKA: I'm comfortable writing on behalf of my company. It's actually part of my job.
- HN comments are lower stakes than a blog post. No long-term SEO impact, for example.
- I've been doing this for 10+ years. And my 500 word comment still took me 90 min to write and edit.
- Yup, I'm a native english speaker.
- Probably some other factors I'm blind to at this point.
It typically takes me 2-3 hours for a well written ~1500 word post. These posts get 3k / mth organic views and many subscribers to my email list, so I know they perform well.
Spending an order of magnitude more time on each post seems ridiculous to me.
Spending an order of magnitude more time on each post seems ridiculous to me.
Do you have any representative posts you could link to?
Ack, unfortunately not publicly. Confidentiality agreements :/ We are permitted to share work privately though. Feel free to email me: [email protected]
The content spectrum goes from plain and often unwanted IP public revelation to blatant shameless plugs, so it really depends on the audience target and the corporate goal ( marketing, conversions, reputation)? I think third party tech journalism such as the IEEE Spectrum or the MIT Technology Review set the tone for engineering blogs these days.
Has anyone experienced with blogs written purely for internal consumption(intranet)? How have it worked out?
We did. Our team provides machine learning ability for our internal products (5-8 products) and we are constantly writing for them to show how artificial intelligence works for these products. So whenever product managers come up with new ideas (e.g. AB testing, promotion based on user data, scam detection), they will contact our team.
We have that at Cloudflare. It's great.
I was denied a request to present, because my head of security didn't want to risk telling the world about my project. Now, they allow presentations, but I have no enthusiasm to present. Making it difficult has a lasting impact.
How do I contact Dan Luu without using Twitter? Is there an email address somewhere I'm not seeing? I'd like to point out a typo :D. Great post.
You can look up the address in his VCS commits, e.g.:
https://github.com/danluu/fs-errors/commit/053b591b123cbc790...
https://github.com/danluu/fs-errors/commit/053b591b123cbc790...
They're on Hacker News pretty often, so maybe they'll see it if you comment here.
Not intentionally trolling, but the lack of formatting on this page immediately brought doubt to anything being said (despite how valid it actually is)
just recently I shared a blog post which I think has done a good job in sharing both the technical and non-technical part https://medium.com/dsaid-govtech/using-robust-optimization-a...
Ironically the post itself is in a CSS-less poor format. Definitely not pleasing to look at, let alone read.
I just wanted to drop the name Gitlab.
More than blogs, they are doing pretty much everything open.
More than blogs, they are doing pretty much everything open.
tldr: fast track post approvals
To be honest I didn't find this a great post. It's only on the sixth paragraph that the post starts to get to the point, and it isn't particularly insightful: organizations write good blog posts when they have simple processes and prioritize it; this is how any effective organization works.
Good blogs also employ some minimal styling to make the content easier to read. The author could slap three lines of CSS into their site and it would be a vastly nicer reading experience.
Good blogs also employ some minimal styling to make the content easier to read. The author could slap three lines of CSS into their site and it would be a vastly nicer reading experience.
[deleted]
Heap CTO here. I'm pretty sure this quote is about me! Or if it's not, it would be equally true about me. This is why we rolled out the "buddy" system described in this post. That way 90% of the iteration can be between the engineer writing the post and someone else who will be a lot more available than I am. This matters a lot if a post requires three or four round trips to really get it right. Plus, in a lot of cases, that other person is better at technical storytelling than I am to begin with.
I'd also note that this post and HN discussion focus a lot on reducing friction, as if having a really good blog is the state of nature. In my experience, this has not been true. A good blog won't just happen if you get out of the way.
Someone senior at the company needs to actively prioritize the engineering blog. You also need eng leadership that respects that writing posts is real work and is willing to have engineers spend time on-the-job working on them. At Heap, we do this down to the level of taking this into account in sprint planning. Also, a lot of the good ideas for posts come from working with engineers to find the kernel of a story in something they're working on. This is an active process, not something spontaneous that you just have to permit to happen.
We also benefit from having a lot of legitimately interesting technical work to talk about. This is more true at some companies than others, and is a big multiplier on how compelling you can make your blog. The success of a blog post is pretty non-linear – either it gets wide readership or not much at all. Having something interesting to talk about is pretty important, and is hard to manufacture.