Not the Docs: content & voice on a developer blog

Not the Docs: content & voice on a developer blog

Havi Hoffman
Write the Docs Portland, May 7, 2018.

My talk about the work I do on Mozilla Hacks, also about empathy and editorial, speaking & writing, luck and imposter syndrome, and the importance of outliers and diverse voices in tech.

"I believe there’s as much appetite for diversity of voice and point of view in blogging about software development as there is in speaking about it at developer conferences. And I’ve got some observations to share about how we can cultivate that."

Here is the full transcript of my talk:

Not the Docs

Hello everyone. Hi. I'm Havi Hoffman, and this is Not the Docs: my talk about content and voice on a developer blog. It’s an honor to be here today, to share some observations with you from my decade + of working in devrel as an editor and content wrangler.

These days, as a member of Mozilla’s Developer Outreach team, I manage Mozilla Hacks, a blog for web developers. In the first 4 months of 2018, we published 38 posts by 29 authors, generating nearly 1.5 million views. And we’re growing!

(Now, I’d like to take a moment to learn just a little about you. Show of hands please. How many documentarians in the house? Brilliant … [Developers? Excellent Writers? Bloggers?] Just one other - Who here has ever given a talk at a conference or event? Thank you!)

You see, there’s a relationship between blogging and conference speaking. A relationship that I’ll be referring to throughout this talk because the connection between written and spoken word is a key dynamic in the work I do, and in the intertwingled stories I’ll share with you today. Developers, designers, documentarians, and ‘devrel’ types who communicate domain knowledge in so many ways: we all write, and many of us speak publicly.

What is the difference between the two? Well, you’ll find wonderful speakers (I think of Saron Yitbarek of code newbies, or Deconstruct’s Gary Bernhardt) who insist emphatically that a talk is NOT a blog post.

And others who’ll tell you, as Sarah Mei does, in recent CFP writing advice - that if you can write a blog post, you can craft a talk.

But whatever your perspective on storytelling - spoken aloud or read on a page, I believe there’s as much appetite for diverse voices and points of view in blogging about software as there is for diverse speakers at tech conferences. And I’ve seen that an editor with the right skills and temperament can attract and empower many voices, whether spoken or written.

I’ll take a closer look at the role of an editor in an engineering environment. It takes non-technical skills to set a tone that’s respectful, reliable and inclusive. To articulate the difference between a puff piece and a story that solves a real problem for a real developer. Or explain why a comprehensive article about keystroke mapping for smart remotes probably belongs in the docs, and not on the blog.

The value we add as editors is incredibly hard to measure and make visible - so I’ll describe the nuances of how it translates into what I do day to day. And I’ll close with a new idea that has recently grabbed my attention.

But first, Denise… I'm giving today's presentation in remembrance, in honor of my friend, Denise Graveline, a blogger and longtime TedX and TedMed speaking coach from Washington, DC.

Denise offered us insight and encouragement in the earliest days of Mozilla Tech Speakers, a program I co-founded three years ago, that supports volunteer web advocates to give talks and workshops at developer conferences around the world.

In 2016, Denise coached 25 Tech Speakers at our first ever speaker meetup in Berlin, and last year, she helped me with my first ever conference talk - and I survived!

I’d hoped that Denise would coach me as I worked on developing this talk. She was deft, and fearless, and kind. We spoke of Write the Docs the very last time we talked in late January.

I knew she’d been ill, but when I learned of Denise’s passing, barely two weeks after our last call, I felt profoundly abandoned and unprepared. That’s what loss is. And I decided that the best thing I could do with my grief would be to channel it into this talk as a way to lean on Denise one more time, and thank her for the confidence she instilled.

And as a reminder to us all that if you can share what you know to help others, which is what documentarians do--and what Denise Graveline did--then you too will live on in the hearts and minds of the people you help, long after you are dust.

If you remember one thing from this talk, remember that! It’s about as real as I get.

But. This dedication is relevant in other ways, as I think you’ll see.

Denise kept a blog called The Eloquent Woman. In her work, she embodied that eloquence – and brought it out in others. She shared the skills of preparation and presentation: the art of being oneself as a public speaker no matter the obstacles, inner or outer. (I’ll speak of these again).

Denise's blog collected speeches by women, women who spoke out despite all the forces trying to suppress us. She created the Eloquent Woman's index of over 250 speeches, from Amelia Earhart’s, "A Woman's Place in Science" to Portland's own Ursula Le Guin, who also passed on this winter.

It was Ursula Le Guin who said in a famous commencement speech many years ago, "When women speak truly, they speak subversively. They can't help it. ...

“We are volcanoes. When we women offer our experience as our truth, as human truth, all the maps change.

There are new mountains. “

So, it’s out of new mountains and against some odds that I come to you today, to share what I know, to map some territory together.

Here’s my daily context: The blog I “manage”, Mozilla Hacks (, is closely aligned with the vast and venerable MDN Web Docs website, and the many engineering projects, large and small, that go on at Mozilla.

We cover a broad swath of technical territory, up and down the stack, in and out of the Firefox browser.

Rather than dazzle you with the renewed relevance of Mozilla, and the resurgence of the splendid Firefox, a story that others tell with much greater authority, I speak here from my own unlikely personal story -- the story of a writer and an editor who’s always felt like an outlier in an industry that skews young, male, and entitled. And perhaps nowhere more so than in Silicon Valley, where I’ve lived and worked since 1999.

I think, though, that my experience is not entirely unique.

Let me tell you about Gloria Dwomoh. In the autumn of 2015, a colleague at Mozilla connected me with his Outreachy intern.

Outreachy is a program that provides paid 3-month remote internships for people from groups traditionally underrepresented in tech. Peter wanted Hacks to publish a blog post by his intern. Gloria was a computer engineering student at Piraeus University of Applied Sciences.

Born in Greece of Ghanaian heritage, at the time we met online Gloria had never given a talk at a tech conference or meetup… But she was not afraid to write. She’d written hundreds of applications and sent them everywhere - for scholarships, internships, fellowships, competitions, writing her way to opportunity.

I published her blog post.

Fast forward almost 3 years. Gloria has now completed her engineering studies, defending her undergrad thesis ("Movement of a Robotic Arm through Bluetooth Communication Between an Arduino and an Android Application"). As a Mozilla Tech Speaker, she’s given talks at conferences in Belgium, England, Greece, and Italy. And she still blogs!

Our backgrounds and life experiences could hardly be more different. And yet, Gloria Dwomoh and I share common ground: she practices everyday empathy by means of ‘active listening’ and I practice ‘empathic editorial’. We both also understand more than a little about LUCK -the luck that allowed us to meet at an opportune moment - and the earned luck of outsiders who find themselves with an entry ticket to a club we never imagined belonging to: the tech industry, the people who make the Internet.

Luck like this often comes with an anti-pattern I’m pretty sure you’ve heard of: Imposter syndrome -- An anti-pattern I’ll speak more about - in just a moment . In March, I came across a Scientific American article titled ... “The Role of Luck in Life Success Is Far Greater Than We Realized”

The piece describes a pioneering effort to quantify the roles of talent and luck in successful careers. A mathematical model designed by 2 physicists and 1 economist found that mediocre but lucky people tend to have more success than people who are more talented but less lucky. The model advises that the best funding strategy for business innovation is to focus, not so much on talent, as on diversity. That it’s worth investing in people who are not necessarily ‘excellent like you.’ People who might be outliers, like Gloria, or me.

In fact, I’ve been incredibly lucky more than once in my life -

I've been in the right place at the right time, with better than reasonable access, and just enough of a good education to get myself a foot in the door, in the heady days of Web 1.0.

Yet, for all that, the feelings associated with impostor syndrome – the sense that I don't belong here among young wizards who can commit code from a smartphone while riding a bicycle, or generate memes from their wristwatch, let alone install fonts at the airport – that sense of having some inadequacies to hide, has stayed close, like Pigpen's cloud, cloaking my light.

When I moved back to the Bay Area in 1995, I had an ISDN internet connection, which gave me a huge access advantage. I’d been trained from childhood to think in hyperlinks, and understand the notion of a web of documents. And the power of network effects.

I could write a sentence. I could turn a phrase. I could spot a story or character, and I had a tale or two of my mine to tell. I landed a contract job writing blurbs and cataloguing websites for a search company.

...and I've been at it ever since, curating and creating content for the web. And programs and events for people who write code and build software.

I fell in love with blogs and blogging early on, as they evolved out of the unlikely marriage of changelogs and personal homepages, from geocities to live journal and movable type; to blogger and typepad; to Wordpress, tumblr and Medium. And back to WordPress, where I still live many hours of my work week

So here I am. A woman in tech. 42 years old when I got my first job on the Internet. You do the math. Over the years, I’ve taken pains to lie low, pushing others into the limelight, onto a stage or a page or a bookshelf – where I never felt I fully belonged. Imposter syndrome, right? But lately, I've challenged myself to become more visible. To take credit for my own work. To see if what I have to say – what I know – might help others express themselves better, and collaborate more effectively.

One of the wisdoms that seasoned ‘oldsters’ bring to the workplace is an understanding of how lucky we are, we who are knowledge workers here, in tech these days. Incredibly lucky. We have privileged positions.

And with luck comes responsibility. Not entitlement.

In our industry, I see an epidemic of imposter syndrome. I also see a consistent undervaluing of humility and dependability – skills that get work done; that ship software. Subtle skills. Let’s give those skills the respect they deserve.

According to Wikipedia, the term ‘soft skills’ was first spotted in print in a US Army manual, in 1972.

I bring a quirky kit of soft skills to the editor’s role: an inexhaustible fascination with language, deep muscle memory for wordsmithing English, and a knack for names and faces. Over the years, I’ve helped programmers write books and articles, and talk about the things they were building.

I’ve thought a great deal about my role on the web, helping divas of code find their voice, or their podium -

According to Wikipedia, the term ‘soft skills’ was first spotted in print in a US Army manual, in 1972.

I bring a quirky kit of soft skills to the editor’s role: an inexhaustible fascination with language, deep muscle memory for wordsmithing English, and a knack for names and faces. Over the years, I’ve helped programmers write books and articles, and talk about the things they were building.

I’ve thought a great deal about my role on the web, helping divas of code find their voice, or their podium -

In a TED talk about alternatives to the corporate pecking order, Heffernan describes a workplace where anyone in the organization could obtain an answer to a timely knowledge question in 17 minutes or less. SAP was creating a transparent environment across their businesses, removing forced ranking and the mindset of a competitive winner-take-all culture.

They gave people opportunities and incentives to be friendly and get to know each other. Information flowed to where it was needed, because people were motivated to help their colleagues across the entire org.

Helpfulness, coded into culture.

Let me tie that back to the work of the Hacks blog. I think we can agree that open source culture has its own version of hierarchical pecking orders; and decentralized collaboration has unique challenges and protocols of helpfulness.

At Mozilla, as makers of the Firefox browser, web developers and designers are alpha ‘customers’ and our most rigorous consumers.

With a vast potential audience of designers and developers, seeking many flavors of help and information, it’s possible to share a range of expertise and speak to multiple segments and communities of interest. A sprawl of topics means that the voices of many technical Mozillians can be heard.

Every organization needs people who can find & tell stories that seed conversation and spread knowledge. People who generate interesting news.

In publishing Hacks, we build a channel for storytellers and their narratives -- and share them with the rest of the web. I publish the work of amazing colleagues, and look out for new voices always.

The most significant dynamic, the one I try to keep top of mind always, is the conversation between reader and writer - and how I can grease it, gracefully.

The original blogs belonged to single authors, but today the genre embraces highly designed online publications. Mozilla Hacks keeps a certain down-home look and feel, but don’t be fooled: our goal is to open minds and influence developer behavior. And, in so doing, help keep the web open and accessible for all.

An editor who manages a multi-author, multi-stakeholder publication, plays many roles. As Jen Geacone-Cruz's tweet describes: (she writes):

Textual micro surgeon, ego tamer, fact guardian, common sense sorceress, cognitive magician, content maven, writes too

Our role is intermediary as much as gatekeeper.

I help the writer communicate as clearly and effectively as possible in her own words and voice.

And I help the reader get good value too, from time invested in discovery, and then in reading. The usual best practices apply - don’t bury the lede, close with a call to action. Remove unnecessary words. Simplify language.

But best practice doesn’t mean a linguistic monoculture. Voice emerges from scores of small decisions that favor individual choice over rigid stylistic consistency. I let British English and spelling exist adjacent to American usage, (though not in the same post!).

I’m comfortable with a range of tone, degrees of formality. I’ve grown vigilant in the use of inclusive and accessible language.

Sometimes, a person’s native language syntax slips in, overlaying the English with a certain, je ne sais quoi. Let it stay! I believe this builds trust. I want the reader to think: this was written by a human, like me. I want the writer to say: you make me sound like myself only more so.

The most important thing I do – the most important thing an editor can do – is establish context. Context links reader and writer most deeply.

There’s a great conference talk by Erin McKean, who’ll be here on stage tomorrow – and it’s called Making the implicit explicit.

The title nails it. Erin cites research from the psychologist Jean Piaget, showing that we’re very likely to overestimate the extent to which another person's knowledge mirrors our own. We tend to think that other people know exactly what we know. And they do not. What’s implicit for me is not implicit for you.

This can be a challenge if you’re a domain expert--- immersed in your subject or your project, you may not know exactly what it is you do know. And what other people need to know to follow along.

So we make the implicit explicit. By providing context. At the semantic level of editing, it’s what I look for first.

Links work to establish context. They’re orientation aids. As are section headers, introductions, illustrations, bullets, resource lists, embeds. If you’re writing – or speaking – locate your territory on a map your audience has seen before. And when the maps are new, annotate, and lead gently.

Which brings me to my closing directive: Experiment. Always explore and experiment, or you’ll soon be obsolete. Embrace new formats, new topics, and new tools.

In January, the Rust community team, engaged in building and extending the Rust programming language (safe, concurrent, & fast) announced a decentralized call for blog posts to collect feedback on their 2018 roadmap. Over 100 posts came in and the team read them all. These inputs informed the Rust plan and priorities.

A volunteer built the Read Rust site, to aggregate and redistribute themed posts in a variety of consumable formats.

They’re calling this project the Content-o-tron! Open channel/topical blogging -- by any name - seems like a brilliant way to feed serendipity and make decentralized participation easier. A way to discover articulate new voices in your own communities --- and to channel verbosity and strong opinion constructively!

An experiment I’m planning to try.

Because some ideas are contagious, and beg to be copied and tested and tweaked. I’ll let you know about this one.

I’d like to close with what Denise Graveline said to a roomful of Tech Speakers, meeting in person for the first time, all of us far from home, at the opening of our workshop: (she said)

“public speaking is a risk that you take, every time you get up to speak.

And Every time someone speaks, you all will be learning with them... “

So I hope you all have been learning with me today - about the hard to measure impact of the soft skill of helpfulness in the work we all do as technical communicators.

And how the know-how and the knack for doing this work, is sometimes found, among industry ‘outsiders’, folks with hybrid skills and unlikely backgrounds. There’s satisfaction in sharing what we know and what luck has given us - and I’m happy for this chance to be like Johnny Appleseed, and spread some ideas with you. Thanks for your attention.

And finally, if you came to this talk hoping to learn more about Mozilla’s work - or if you have a great idea for an article that you think would be a great fit for Hacks, or if you want to ask me about a couple of contract writing positions on the MDN docs team, please come find me here today or tomorrow or later on the internets. I’d love to talk with you.


havi hoffman

May 07, 2018


  1. Not the Docs: content & voice on a developer blog

    Havi Hoffman, Mozilla May 7, 2018 Write the Docs, Portland
  2. None
  3. april 2018


  5. None
  6. the yin & yang of editor & engineers

  7. Denise Graveline


  9. None
  10. The Eloquent Woman Index of Famous Speeches by Women

  11. Ursula K. LeGuin

  12. None
  13. “We are volcanos. When we women offer our experience as

    our truth, as human truth, all the maps change. There are new mountains.” Ursula K. LeGuin, 1986
  14. Credit: Mount St. Helens National Volcanic Monument - Jasperdo

    (CC BY-NC-ND 2.0) new mountains

  16. None
  17. University Ave. Palo Alto, CA, 2006

  18. Gloria Dwomoh

  19. paid internships for under-represented people in tech

  20. “It was a spring night in Greece when I got

    the news I’d been selected by Mozilla to be an Outreachy intern… That night, I was the happiest person in my town, I believe…” Gloria Dwomoh, 2015
  21. “Movement of a Robotic Arm through Bluetooth Communication Between an

    Arduino and an Android Application” Gloria Dwomoh, 2017
  22. Mozilla Tech Speakers at FOSDEM, February 2018

  23. anti-pattern: imposter syndrome

  24. “An anti-pattern is a common response to a recurring problem

    that is usually ineffective and risks being highly counterproductive.”
  25. None
  26. soft skills & good luck

  27. None
  28. None
  29. Clay Shirky, Hudson Theater, Open Hack NYC 2009

  30. the first blogher, 2005 San Jose, CA.

  31. Open Hack EU Team, Bucharest, Romania, 2011

  32. an epidemic of imposter syndrome

  33. Soft skills : “These skills can include social graces, communication

    abilities, language skills, personal habits, cognitive or emotional empathy, time management, teamwork, and leadership traits.”
  34. Margaret Heffernan

  35. None
  36. “Helpfulness means I don't have to know everything, I just

    have to work among people who are good at getting and giving help. “ Margaret Heffernan
  37. 2012

  38. None
  39. None
  40. Inside a super fast CSS engine: Quantum CSS code cartoon

    by Lin Clark @linclark quantum-css-aka-stylo/
  41. How to Write CSS That Works in Every Browser, Even

    the Old Ones By Jen Simmons @jensimmons Resilient CSS in 7 video episodes, wrapped in a blog post. orks-in-every-browser-even-the-old-ones/
  42. None
  43. the yin & yang of reader & writer

  44. “Our aim is always to be useful and witty, but

    never sarcastic, spiteful, or snarky.” Danielle Vincent, 2018 Mozilla Developer Newsletter
  45. what Erin McKean taught me about context


  47. Online Communities

  48. None
  49. Illustration by Ashley Williams @ag_dubs

  50. None
  51. “Public speaking is a risk that you take, every time

    you get up to speak. And every time someone speaks, you all will be learning with them..” Denise Graveline
  52. Thank you! twitter: @freshelectrons | @mozhacks | @moztechspeakers medium: @freshelectrons Slides by Mike McFarland Design