Content is Community

At Keen IO, I have been tasked with community building and developer advocacy. Being a developer advocate at Keen IO requires administrating an array of services, social media, support on our Community Slack channel, blog, technical content, and more. We have learned quite a lot supporting and creating a community for developers and engineers all over the globe. Over the years we’ve learned that great content is great developer advocacy.

The team at Keen believes in creating meaningful and helpful content. Engineers and developer advocates all believe in the value of writing to be helpful to the point where many of our pieces on our blog often deal with being a human more often than it deals with our technology. (For example, what it’s like working remote, the fears and feels about switching careers, finding meaning at work, work-life balance, and how to negotiate your startup compensation to name a few.) After all, humans do run a company; and while you spend just part of your career working in technology, you spend all of your life, being human.

So why write? We hope to share a few of our reasons for believing in good developer content and documentation and share some of what we learned supporting and growing a developer community through online community and content.

To Be Helpful

Full disclosure: Being helpful is both altruistic but selfish. Helpfulness provides:

• Clarity on product usage features
• Makes things easy for the people we built things for
• Less confusion and less questions

Compared to our early days when we made all kinds of mistakes, we now often receive compliments for our developer content and API documentation. We make it standard practice reach out to see if developers integrating Keen need help, and the most rewarding messages have been: “Thanks for the offer. Not at all! Your documentation was super straightforward and I don’t need any help!” and “I found Keen because I was reading your blog article about team culture. Your product is super easy to use!”

Writing to your audience provides clear benefits. It feels good to help people and provide a reference for someone searching for an example or answer.

To Develop Empathy

In addition to helping us build a clear sense of community and a voice for our company, we get the amazing opportunity to connect with developers and provide reasons for why things are done. It’s an opportunity for product owners and our platform engineers to be real with our users and understand the struggles of our users. Because we are human, it is important to have reasons and logic for why things are done.

For us as people who work hard on creating and supporting Keen IO’s databases, we read comments, interact, and think about customers, which helps us stay in tune with who we’re helping and get into our customers’ shoes.

Because If You Don’t Write, It Doesn’t Exist

On engineering and platform, it’s easy to get carried away creating and deploying new features. Project tasks include everything from testing and deploying to production, but it’s easy to overlook adding to the project plan that final step of publishing the feature before moving on to the next task in your sprint. It’s been conveyed to me that thinking about writing or documenting can often feel cumbersome, like it’s getting in the way and there’s a high activation energy required to get rolling. This is an easy thought process to fall into and a rut that fails to help.

Without providing clear and helpful documentation, or deploying some content to our API reference, customers are left in the dark. To fend for themselves. Worse 😧 — they’ll never use the awesome thing you built just for them!

On our Community Team, we’ve made it best practice to encourage our engineering teammates and help create mini milestones to fill in that missing piece on project plans. For those who are nervous about writing — that it might not be perfect, or that what is written is permanent, and will be seen by thousands, and they don’t want to fail — our awesome developer advocates help interview creators of the features and start up drafts or outlines. In the end, we’re motivated by being helpful! Having technical content and API documentation helps the customers that we’ve built things for.

There is a debate that often happens, “should I invest the time it takes to write good documentation.” Yes. “If I write, what if it’s not perfect?”

Don’t sweat the small stuff. In our experience, definitely put it out there. Good is good enough, and people digging into the sample code you wrote are happy to have an example. They’re usually pretty nice if they find a syntax error, and if they’ve found a brilliant solution are more than willing to share. Our Community Slack account is full of examples of strangers helping strangers, and StackOverflow comments show helpful and innovative solutions.

Lessons Learned on Writing Good Documentation

A lot of the knowledge we’ve stumbled upon in our journey as a developer company were revealed because of comments and suggestions provided by our customers. We know now what we could have done to be stellar right off the bat. Here are some do’s and don’ts we wish we’d known.

Format Matters

With so much to cover, long blocks of text used to dominate our how-to guides and articles. Based on pageview analytics and the type of questions we were receiving, when we didn’t give any thought to format, users gave up and would leave the page.

The format your content is in matters — it adds clarity to instructions. Some content hacks that helped technical people scan and find the answers they were looking for:

• Search bar, top and center
  (Can you believe that we didn’t even have a search function for years?! Using Algolia for docs search improved our world for the better.)
• Table of contents, top of page (help long articles become less overwhelming, links jump to particular subtopics of interest)
• Anchors for subsections (helps content appear directly as entries on Google search results)
• Layout, left side navigation

Don’t Skip Steps

Do write out every step even if it seems basic to you. It’s good for placeholders, and people who are familiar with your instructions can still orient themselves and will skip the parts they know. Others encountering the instructions for the first time will be lost.

Have peers that are on and off your team review your writing. Having a few perspectives help because what is obvious or clear to one person may not be for another. One thing we try to avoid in documentation is using language like “just” “simply”. Sometimes, it’s not as simple to developers who haven’t worked on your code base for years.

To help readers follow along, visuals punctuated throughout the article don’t hurt either.

Keep It Real

Being able to laugh at your own short comings or being okay with casual language is all right.

Embedded and spread out through documentation, I’ve written sly references to Game of Thrones, Minecraft, or other things to brighten and add some humor when talking about and documenting data analytics. They’re not always in text because we don’t necessarily want them to be indexed by bots or search engines.

At times, we punctate our documentation with these secret jokes and winks to insiders to make sure people are still awake. On the Keen site there’s a few fun or funny things hidden in documentation. Perhaps our most famous is our developer easter egg, but you’ll have to find that one yourself 😜