[HN Gopher] How some good corporate engineering blogs are written
___________________________________________________________________
How some good corporate engineering blogs are written
Author : jgrahamc
Score : 482 points
Date : 2020-03-11 10:52 UTC (12 hours ago)
(HTM) web link (danluu.com)
(TXT) w3m dump (danluu.com)
| NPMaxwell wrote:
| 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.
| sciyoshi wrote:
| 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.
| bbrazil wrote:
| 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.
| jgrahamc wrote:
| 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).
| detaro wrote:
| 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"
| ksahin wrote:
| 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 wrote:
| > 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?
| heligate229 wrote:
| 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...
| brian_cunnie wrote:
| 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/
| pulkitsh1234 wrote:
| 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...
| jgrahamc wrote:
| 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.
| samsolomon wrote:
| 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/
| stoksc wrote:
| 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.
| gumby wrote:
| > 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.
| btrettel wrote:
| 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.
| CM30 wrote:
| 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.
| detaro wrote:
| 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)
| j1elo wrote:
| 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)...
| craigkerstiens wrote:
| 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...
| austincheney wrote:
| 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.
| [deleted]
| [deleted]
| VonGuard wrote:
| 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.
| franciscop wrote:
| > 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...
| SeanFerree wrote:
| Awesome article!
| kevinmannix wrote:
| 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.
| lucaspottersky wrote:
| tldr: fast track post approvals
| melenaos wrote:
| 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.
| jordache wrote:
| Has anyone experienced with blogs written purely for internal
| consumption(intranet)? How have it worked out?
| jgrahamc wrote:
| We have that at Cloudflare. It's great.
| chenlianmt wrote:
| 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.
| FrostAlot wrote:
| 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
| Havoc wrote:
| 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.
| jgrahamc wrote:
| > 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.
| thedance wrote:
| 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.
| qznc wrote:
| 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.
| hyperman1 wrote:
| 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.
| giancarlostoro wrote:
| 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 wrote:
| 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.
| throwaway13000 wrote:
| What is the purpose of engineering blogs? Is it only to attract
| engineers to work for you?
| zffr wrote:
| It also provides exposure and recognition for the engineers who
| write content for them, or who have their technologies features
| in the blog posts.
| MisterTea wrote:
| 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.
| Funes- wrote:
| 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 wrote:
| 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.
| CM30 wrote:
| 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'.
| Goladus wrote:
| > 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.
| heligate229 wrote:
| 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...
| rkangel wrote:
| 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.
| alxlaz wrote:
| > 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.
| andrewzah wrote:
| > 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.
| alxlaz wrote:
| > 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).
| saagarjha wrote:
| 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.)
| mooreds wrote:
| 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 wrote:
| 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 wrote:
| 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 wrote:
| > It'd be a coup for the open source security researchers.
|
| How so?
| whatshisface wrote:
| > _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.
| sarabande wrote:
| 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 wrote:
| They're on Hacker News pretty often, so maybe they'll see it if
| you comment here.
| jwilk wrote:
| You can look up the address in his VCS commits, e.g.:
|
| https://github.com/danluu/fs-errors/commit/053b591b123cbc790...
| nickdothutton wrote:
| 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.
| papito wrote:
| 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.
| craigkerstiens wrote:
| 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.
| drdrey wrote:
| > 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.
| DrNuke wrote:
| 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.
| rv-de wrote:
| 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 wrote:
| 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.
| noelwelsh wrote:
| 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.
| behnamoh wrote:
| Ironically the post itself is in a CSS-less poor format.
| Definitely not pleasing to look at, let alone read.
| magd wrote:
| 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.
| Jackson-Solway wrote:
| 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/, [2]
| https://www.jobportraits.com/services/tech-blog-post-subscri...
| SpicyLemonZest wrote:
| > 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?
| Jackson-Solway wrote:
| 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.
| jefftk wrote:
| Do you have any representative posts you could link to?
| Jackson-Solway wrote:
| Ack, unfortunately not publicly. Confidentiality agreements
| :/ We are permitted to share work privately though. Feel free
| to email me: jackson@jobportraits.com
| michaelthiessen wrote:
| 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.
| chenlianmt wrote:
| - "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.
| drob wrote:
| > 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.
| swyx wrote:
| > 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"?
| drob wrote:
| > 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.
| craigkerstiens wrote:
| 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.
| drob wrote:
| :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. :)
| gowld wrote:
| 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?
| a1pulley wrote:
| Anyone have thoughts on companies that don't include authors'
| names in blog posts? My (big N) employer anonymizes our technical
| blog posts.
| reboog711 wrote:
| I wouldn't write for that company's blog; unless there was some
| huge internal incentive to do so.
| draw_down wrote:
| 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.
| thundergolfer wrote:
| 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...
| bndw wrote:
| > 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
| stuxnet79 wrote:
| 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.
___________________________________________________________________
(page generated 2020-03-11 23:00 UTC)