14 ms·

How some good corporate engineering blogs are written

617 points by jgrahamc 7y ago

noelwelsh 7y ago
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.
thundergolfer 7y ago
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-product-ranking-at-wayfair/ https://tech.wayfair.com/data-science/2020/01/bayesian-produ... 2. https://eng.lyft.com/how-lyft-designs-the-machine-learning-software-engineering-interview-bbbb9fc8bb28 https://eng.lyft.com/how-lyft-designs-the-machine-learning-s...
- stuxnet79 7y ago
  Wayfair's tech stack is kind of a dumpster fire -> https://www.teamblind.com/post/Technical-incompetence-at-Wayfair----is-there-anything-worse-43wn8iLT https://www.teamblind.com/post/Technical-incompetence-at-Way... I would read through their engineering blogs with a critical eye.
- bndw 7y ago
  > 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 https://medium.com/@mattklein123
- ryan_lane 7y ago
  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.
  - thundergolfer 7y ago
    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 https://news.ycombinator.com/item?id=21409066
ksahin 7y ago
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.
- zeveb 7y ago
  > 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?
- pR0Ps 7y ago
  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 https://segment.com/blog/atom.xml [2]: https://emojipedia.org/police-car-light/ https://emojipedia.org/police-car-light/
sciyoshi 7y ago
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.
- detaro 7y ago
  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"
- jgrahamc 7y ago
  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).
- bbrazil 7y ago
  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.
pulkitsh1234 7y ago
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://www.websequencediagrams.com/, https://mermaid-js.github.io/mermaid/#/ https://mermaid-js.github.io/mermaid/#/ [2]: https://www.toptal.com/ruby-on-rails/decoupling-rails-components https://www.toptal.com/ruby-on-rails/decoupling-rails-compon... [3]: https://blog.cloudflare.com/content/images/2019/06/leak2-2.png https://blog.cloudflare.com/content/images/2019/06/leak2-2.p...
- samsolomon 7y ago
  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/
  - stoksc 7y ago
    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.
    - detaro 7y ago
      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)
Havoc 7y ago
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.
- giancarlostoro 7y ago
  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.
- mooreds 7y ago
  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.
- hyperman1 7y ago
  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 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.
mooreds 7y ago
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.
- gonzo41 7y ago
  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.
  - mooreds 7y ago
    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.
  - saagarjha 7y ago
    > It'd be a coup for the open source security researchers. How so?
sarabande 7y ago
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.
- saagarjha 7y ago
  They're on Hacker News pretty often, so maybe they'll see it if you comment here.
- jwilk 7y ago
  You can look up the address in his VCS commits, e.g.: https://github.com/danluu/fs-errors/commit/053b591b123cbc79055461a43a7f208561753e27.patch https://github.com/danluu/fs-errors/commit/053b591b123cbc790...
nickdothutton 7y ago
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.
Funes- 7y ago
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.
alxlaz 7y ago
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.
- andrewzah 7y ago
  > 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.
papito 7y ago
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.
- drdrey 7y ago
  > 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.
- craigkerstiens 7y ago
  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.
Jackson-Solway 7y ago
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 :) jackson@jobportraits.com [1] https://www.jobportraits.com/ https://www.jobportraits.com/, [2] https://www.jobportraits.com/services/tech-blog-post-subscription https://www.jobportraits.com/services/tech-blog-post-subscri...
brian_cunnie 7y ago
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/ http://engineering.pivotal.io/
franciscop 7y ago
> 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-source-32ok https://dev.to/fpresencia/contributing-to-js-react-open-sour...
whatshisface 7y ago
>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.
rv-de 7y ago
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.
TheRealDunkirk 7y ago
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.
draw_down 7y ago
Where I work it takes about 6 months to get a blog post out the door. I don’t really understand what specifically is going on during that time. A year ago or so, there was a push to get more content on the eng blog. This consisted of calling more volunteers to write posts, not any revision to the extremely onerous process.
deleted 7y ago
[deleted]
VonGuard 7y ago
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.
DrNuke 7y ago
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.
drob 7y ago
> 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. 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.
- craigkerstiens 7y ago
  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.
NPMaxwell 7y ago
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.
jordache 7y ago
Has anyone experienced with blogs written purely for internal consumption(intranet)? How have it worked out?
- jgrahamc 7y ago
  We have that at Cloudflare. It's great.
- chenlianmt 7y ago
  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.
chenlianmt 7y ago
- "added writing and speaking as explicit criteria to be rewarded in performance reviews and career ladders". So true. Writing a compelling blog post with attractive figures and solid results is incredibly time-consuming. It doesn't worth it if it's not appreciated in performance reviews. Sharing with others is not that great when your boss thought you produced nothing in weekly reports.
kevinmannix 7y ago
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/ 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.
throwaway13000 7y ago
What is the purpose of engineering blogs? Is it only to attract engineers to work for you?
- MisterTea 7y ago
  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.
- zffr 7y ago
  It also provides exposure and recognition for the engineers who write content for them, or who have their technologies features in the blog posts.
melenaos 7y ago
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.
magd 7y ago
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.
SeanFerree 7y ago
Awesome article!
heligate229 7y ago
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-and-mixed-integer-programming-to-manage-singapores-water-resources-a0b899afe601 https://medium.com/dsaid-govtech/using-robust-optimization-a...
lucaspottersky 7y ago
tldr: fast track post approvals
behnamoh 7y ago
Ironically the post itself is in a CSS-less poor format. Definitely not pleasing to look at, let alone read.
a1pulley 7y ago
Anyone have thoughts on companies that don't include authors' names in blog posts? My (big N) employer anonymizes our technical blog posts.
- reboog711 7y ago
  I wouldn't write for that company's blog; unless there was some huge internal incentive to do so.
  - a1pulley 7y ago
    Would it affect your decision to apply to the company?
FrostAlot 7y ago
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 http://techblogz.co. It currently has 10k entries from different corporate engineering blogs. Would love to hear your feedback on it. Thanks
KerryJones 7y ago
Not intentionally trolling, but the lack of formatting on this page immediately brought doubt to anything being said (despite how valid it actually is)
vira28 7y ago
I just wanted to drop the name Gitlab. More than blogs, they are doing pretty much everything open.

617 points by jgrahamc 7y ago

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.

thundergolfer 7y ago

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-product-ranking-at-wayfair/ https://tech.wayfair.com/data-science/2020/01/bayesian-produ... 2. https://eng.lyft.com/how-lyft-designs-the-machine-learning-software-engineering-interview-bbbb9fc8bb28 https://eng.lyft.com/how-lyft-designs-the-machine-learning-s...

stuxnet79 7y ago
Wayfair's tech stack is kind of a dumpster fire -> https://www.teamblind.com/post/Technical-incompetence-at-Wayfair----is-there-anything-worse-43wn8iLT https://www.teamblind.com/post/Technical-incompetence-at-Way... I would read through their engineering blogs with a critical eye.
bndw 7y ago
> 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 https://medium.com/@mattklein123
ryan_lane 7y ago
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.
- thundergolfer 7y ago
  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 https://news.ycombinator.com/item?id=21409066

ksahin 7y ago

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.

zeveb 7y ago
> 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?
pR0Ps 7y ago
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 https://segment.com/blog/atom.xml [2]: https://emojipedia.org/police-car-light/ https://emojipedia.org/police-car-light/

sciyoshi 7y ago

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.

detaro 7y ago
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"
jgrahamc 7y ago
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).
bbrazil 7y ago
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.

pulkitsh1234 7y ago

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://www.websequencediagrams.com/, https://mermaid-js.github.io/mermaid/#/ https://mermaid-js.github.io/mermaid/#/ [2]: https://www.toptal.com/ruby-on-rails/decoupling-rails-components https://www.toptal.com/ruby-on-rails/decoupling-rails-compon... [3]: https://blog.cloudflare.com/content/images/2019/06/leak2-2.png https://blog.cloudflare.com/content/images/2019/06/leak2-2.p...

samsolomon 7y ago
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/
- stoksc 7y ago
  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.
  - detaro 7y ago
    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)

Havoc 7y ago

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.

giancarlostoro 7y ago
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.
mooreds 7y ago
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.
hyperman1 7y ago
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 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.

mooreds 7y ago

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.

gonzo41 7y ago
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.
- mooreds 7y ago
  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.
- saagarjha 7y ago
  > It'd be a coup for the open source security researchers. How so?

sarabande 7y ago

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.

saagarjha 7y ago
They're on Hacker News pretty often, so maybe they'll see it if you comment here.
jwilk 7y ago
You can look up the address in his VCS commits, e.g.: https://github.com/danluu/fs-errors/commit/053b591b123cbc79055461a43a7f208561753e27.patch https://github.com/danluu/fs-errors/commit/053b591b123cbc790...

nickdothutton 7y ago

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.

Funes- 7y ago

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.

alxlaz 7y ago

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.

andrewzah 7y ago
> 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.

papito 7y ago

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.

drdrey 7y ago
> 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.
craigkerstiens 7y ago
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.

Jackson-Solway 7y ago

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 :) jackson@jobportraits.com [1] https://www.jobportraits.com/ https://www.jobportraits.com/, [2] https://www.jobportraits.com/services/tech-blog-post-subscription https://www.jobportraits.com/services/tech-blog-post-subscri...

brian_cunnie 7y ago

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/ http://engineering.pivotal.io/

franciscop 7y ago

> 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-source-32ok https://dev.to/fpresencia/contributing-to-js-react-open-sour...

whatshisface 7y ago

>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.

rv-de 7y ago

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.

TheRealDunkirk 7y ago

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.

draw_down 7y ago

Where I work it takes about 6 months to get a blog post out the door. I don’t really understand what specifically is going on during that time. A year ago or so, there was a push to get more content on the eng blog. This consisted of calling more volunteers to write posts, not any revision to the extremely onerous process.

deleted 7y ago

[deleted]

VonGuard 7y ago

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.

DrNuke 7y ago

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.

drob 7y ago

> 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. 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.

craigkerstiens 7y ago
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.

NPMaxwell 7y ago

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.

jordache 7y ago

Has anyone experienced with blogs written purely for internal consumption(intranet)? How have it worked out?

jgrahamc 7y ago
We have that at Cloudflare. It's great.
chenlianmt 7y ago
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.

chenlianmt 7y ago

- "added writing and speaking as explicit criteria to be rewarded in performance reviews and career ladders". So true. Writing a compelling blog post with attractive figures and solid results is incredibly time-consuming. It doesn't worth it if it's not appreciated in performance reviews. Sharing with others is not that great when your boss thought you produced nothing in weekly reports.

kevinmannix 7y ago

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/ 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.

throwaway13000 7y ago

What is the purpose of engineering blogs? Is it only to attract engineers to work for you?

MisterTea 7y ago
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.
zffr 7y ago
It also provides exposure and recognition for the engineers who write content for them, or who have their technologies features in the blog posts.

melenaos 7y ago

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.

magd 7y ago

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.

SeanFerree 7y ago

Awesome article!

heligate229 7y ago

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-and-mixed-integer-programming-to-manage-singapores-water-resources-a0b899afe601 https://medium.com/dsaid-govtech/using-robust-optimization-a...

lucaspottersky 7y ago

tldr: fast track post approvals

behnamoh 7y ago

Ironically the post itself is in a CSS-less poor format. Definitely not pleasing to look at, let alone read.

a1pulley 7y ago

Anyone have thoughts on companies that don't include authors' names in blog posts? My (big N) employer anonymizes our technical blog posts.

reboog711 7y ago
I wouldn't write for that company's blog; unless there was some huge internal incentive to do so.
- a1pulley 7y ago
  Would it affect your decision to apply to the company?

FrostAlot 7y ago

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 http://techblogz.co. It currently has 10k entries from different corporate engineering blogs. Would love to hear your feedback on it. Thanks

KerryJones 7y ago

Not intentionally trolling, but the lack of formatting on this page immediately brought doubt to anything being said (despite how valid it actually is)

vira28 7y ago

I just wanted to drop the name Gitlab. More than blogs, they are doing pretty much everything open.