
How some good corporate engineering blogs are written - jgrahamc
https://danluu.com/corp-eng-blogs/
======
drob
> 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
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
: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. :)

------
pulkitsh1234
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-compon...](https://www.toptal.com/ruby-on-
rails/decoupling-rails-components) [3]:
[https://blog.cloudflare.com/content/images/2019/06/leak2-2.p...](https://blog.cloudflare.com/content/images/2019/06/leak2-2.png)

~~~
craigkerstiens
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...](http://www.craigkerstiens.com/2011/11/07/how-heroku-works-maker-day/)

~~~
thirdsun
Now that you mention it, Ben Thompson uses this hand drawn art style at
Stratechery[1] - it seems like something that is easy and fast enough to do
with one of the countless iPad drawing apps and an Apple Pencil.

[1]: [https://stratechery.com/](https://stratechery.com/)

------
thundergolfer
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...](https://tech.wayfair.com/data-science/2020/01/bayesian-product-
ranking-at-wayfair/)

2\. [https://eng.lyft.com/how-lyft-designs-the-machine-
learning-s...](https://eng.lyft.com/how-lyft-designs-the-machine-learning-
software-engineering-interview-bbbb9fc8bb28)

~~~
ryan_lane
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
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)

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

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

~~~
saagarjha
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.)

~~~
andrewzah
My definition involves understanding how computers work to a decent degree
outside of basic app usage.

Being mechanically efficient at using computers (and by this, I mean being
efficient at using carefully- designed apps) does not count in my eyes. If any
problem occurs, or if one has to do anything outside of the basic app flow,
then people go blank.

I operate a car daily, does that make me car literate? I understand
mechanically how to operate a car, but if anything out of the ordinary occurs
I have no idea what to do. Except to call someone who is actually car literate
to fix the problem. Usage does not correlate with literacy.

When a problem occurs, I've seen many people not even read the error messages
or display basic critical thinking ability. I can't call this tech literacy.

> They can talk with their friends over the internet, create and layout
> documents, print posters, do research

This is a testament to programmers and UX designers making easy to use
applications, not people being "tech literate".

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

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

~~~
jgrahamc
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).

------
brian_cunnie
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/)

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

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

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

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

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

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

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

~~~
reboog711
I wouldn't write for that company's blog; unless there was some huge internal
incentive to do so.

~~~
a1pulley
Would it affect your decision to apply to the company?

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

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

~~~
pR0Ps
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/)

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

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

------
kevinmannix
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
What is the purpose of engineering blogs? Is it only to attract engineers to
work for you?

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

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

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

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

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

------
Jackson-Solway
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-
subscri...](https://www.jobportraits.com/services/tech-blog-post-subscription)

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

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

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

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

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

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

~~~
jwilk
You can look up the address in his VCS commits, e.g.:

[https://github.com/danluu/fs-
errors/commit/053b591b123cbc790...](https://github.com/danluu/fs-
errors/commit/053b591b123cbc79055461a43a7f208561753e27.patch)

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

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

------
vira28
I just wanted to drop the name Gitlab.

More than blogs, they are doing pretty much everything open.

------
lucaspottersky
tldr: fast track post approvals

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

