Not the Docs: content and voice on a developer blog

At Write The Docs Portland 2018, Havi Hoffman (who is Content Wrangler for the Moz Hacks blog) gave a talk on "Not the Docs – content and voice on a developer blog".

Blogging for developers

Just as a certain style prevails in technical documentation, so too does a similar style determine the most successful developer blogs.

Havi suggested that blogging for developers (about software and tools) is an area that's worth exploring more. There were also many bloggers in the conference so the talk was well-received from that perspective.

She talked about many issues that plague technical writers, others working in the software industry, and people in the working world in general.

An outsider in tech

“I got my foot in the door in the heady days of Web 1.0,” says Havi, in reference to herself being older than many figures who are often worshipped in the tech industry. “I’d been trained from childhood to think in hyperlinks.” She’s also female.

Partly for these reasons, Havi has always felt like an outlier “in an industry that skews young, male and entitled”, and that perhaps her place in the industry is a result of luck as much as anything else.

She got one of her first breaks through her involvement with Outreachy. Outreachy is a group that offers remote internships to under-represented groups, and gives some their first taste of working at companies they had previously only dreamed of.

“They provided us with an entry to ticket to a club we never imagined belonging to” says Havi of herself and another fellow blogger at Outreachy. But perhaps these outliers are the ones who are best-placed to comment on the current state of the tech industry.

Tech is an industry that frequently devalues ‘soft skills’ in favor of the only thing that matters – code. Technical writing can fall into the category of ‘soft skills’. As soft skills are frequently associated with women, this has the effect of driving many women from the industry.

In fact, there is a high percentage of female technical writers compared to their representation in the industry as a whole. 54.5% of US technical writers are female, much higher than the industry average for tech as a whole.  

Fighting imposter syndrome

This relentless focus on stereotypes has the effect of stifling talent. This is partly because industry outsiders are usually folks with hybrid skills and unusual backgrounds.

“I bring my own quirky set of soft skills to software development,” says Havi. Then again, it’s hard to measure the impact of the soft skill of, say, helpfulness. Undervaluing the soft skills that so many career changers bring to the industry is to exacerbate what is commonly known as “Imposter Syndrome”.

"In our industry, I see an epidemic of imposter syndrome and a consistent undervaluing of humility and dependability: the skills that get real work done..." Everyone feels like they are a fraud who will soon be found out. This hinders productivity and wellbeing.

Havi says, “Imposter syndrome – it’s the sense I don’t quite fit in among wizards who can commit code from a smartphone while riding a bicycle.” It’s also the idea that everyone must present a flawless front and excel at – code. In reality, many women have been trained to fade into the background, and have been driven out of development jobs.

Now, Havi is challenging herself to become more visible when she has traditionally championed others. ““Over the years I’ve taken pains to lie low, pushing others into the limelight, but lately I’ve challenged myself to become more visible.”

Marketing to developers

Developers are notoriously mistrustful of marketers, a fact which Havi recognizes in her talk.

“Web developers are alpha customers,” says Havi. “They are the most rigorous consumers, and so it’s really important to get the tone right on the Moz Hacks blog. Our aim is to be useful and witty, but never sarcastic, spiteful or snarky.”

This is also something we think carefully about at KnowledgeOwl. We always want to be helpful to our customers, and never bombard them with our own messages.

Havi advocates for empathic editorial, and empathy means active listening. If you become too obsessed with the style guide, you can lose some of the naturalness that makes blogging so appealing to audiences.

In other words, you don’t want to sound like a robot.

“Let the native language slip into overlay the English with a certain je ne sais quoi… it builds reader trust.” This means not ironing out certain idioms that reveal someone is not a native English speaker, and it means allowing particular turns of phrase through your editing process that may stand out.

Final remarks

Havi views her experiences as showing her the importance of blogging for software, and how it has the potential to empower many voices. Blogging is a democratization of communication. Anyone has the ability to blog – but companies can do more to welcome diverse voices on their blogs.

Havi is grateful for the support of her many female mentors of the years. She dedicated her talk to Denise Graveline, who recently passed away.

As Havi says, “Be yourself, no matter the obstacles. Women can’t help but speak subversively, and when women offer their truth as human truth, all the maps change.”

Check out our other blog post on making your code examples shine in your documentation, and listen to Havi’s full talk on YouTube. 

Images by Kay Smoljak. This work is licensed under a Creative Commons Attribution-Non Commercial-ShareAlike 2.0 Generic License.

KnowledgeOwl is our very own knowledge base software, perfect for technical writers of many stripes. Take KnowldgeOwl for a test drive.