News

Elastic Contributor Program: Tips for creating written content

By
Ricardo Ferreira

At Elastic, we believe in the democratization of knowledge. This is part of our open source roots. The open source model advocates that everyone should have access to code that represents knowledge — which entails research, experimentation, testing, and time. Code is important, but what really makes the difference is the knowledge behind the code, and thanks to open source, this knowledge becomes available for anyone to use, build on, and evolve.

There are tons of ways to share knowledge besides contributing with code, such as organizing meetups, speaking at an event, or creating content. We created the Elastic Contributor Program to encourage knowledge sharing in our community and to recognize and reward the hard work of our awesome contributors.

In this blog post, we’ll cover a few tips on how to get started sharing your experiences with the community in writing.

Getting started

First, let’s clarify what qualifies as written content for the Elastic Contributor Program. In order to receive points the written content must be at least 200 words (or roughly 10 lines) and must be centered on Elastic products or solutions. If you happen to speak more than one language, you can also translate elastic.co blog posts for the chance to earn additional points in the Contributor Program! Be sure to check out the Elastic Contributor Program rules page for the full rules.

The good news is that the rules are pretty open ended — there’s no limit to what you can create! But you might ask yourself: Why should I spend my time writing? One reason is that written content is a great way to showcase your work and build your career. It’s not uncommon for developers in the community to struggle to get acknowledgement because, ultimately, there’s no easy way to verify their work and experience. Sharing your work by putting your experiences into writing is an effective way to demonstrate your abilities while also helping other developers learn from you.

Finding a topic to write about

So you’ve decided to take the leap and write something — but where do you begin? You might think that the first step in writing something is to get creative. But instead of focusing on creativity, try focusing on your personal experiences. Carefully observe what you’re building in your work every day. Take a closer look at the small things you create, change, and improve to get something done. You’ll probably find lots of interesting things to talk about.

Writing based on personal experience is powerful because it allows us to share practical experience, which everybody loves. For example, a blog post that talks about controlling memory usage for aggregations in Elasticsearch is good — but a post that discusses which knobs you had to switch to achieve faster aggregation results is way better.

As you start to think about putting your experiences down in writing, consider telling your story in one of the following ways:

  • Journey: A journey is one of the most popular story types. Your journey captures the decisions, struggles, and consequences that you went through in order to accomplish something. To tell an effective story, you’ll want to explain the trajectory you took to get to your desired outcome — for example, maybe you had a project where you migrated from single indices to data streams to handle time series data more efficiently using hot, warm, and cold data nodes. Be sure to explain the desired outcome before getting into the details of the journey so your readers can understand the steps you took. Your readers might be trying to accomplish the same thing and they’ll want to know if your journey is applicable to them.
  • Use case: A use case story is a variation of a journey, but is more structured and usually has four main sections: context, problem, solution, and results. Use case stories are good for sharing the history of a project, and they tend to be more successful when they focus on a specific industry. For instance, two companies adopting Elastic APM will end up with the same benefits, but if they’re in different industries their individual use cases will be unique. Capturing this uniqueness is key for telling a use case story.
  • Lessons learned: This type of content focuses on the things that you’ve learned while working with a specific technology. It’s impossible for a technology to foresee all possible scenarios where it will be used, so if you’ve discovered something new during your work with the technology then this is a great opportunity to write something up. It’s common to use a cause and effect framework for this type of story. The effect is what readers are looking to understand. For example, do you know how Elasticsearch may behave when used with the new garbage collector from the JDK 12? What are the pros and cons? If this piqued your interest, then it may pique someone else’s, too.

Turning ideas into action

So far we’ve covered how to come up with ideas for what to write about. But how do you actually start the writing process?

First, before you even get your first word down, remember: writing isn’t about producing something that’s perfect. Instead, focus on creating something that will be useful to your reader. In order to do that, it’s important to understand your target audience. Properly understanding your audience will help a lot in managing your expectations about how much effort and time to put in your work — which hopefully will lead to less frustration.

For example, if you’re planning to write about a lesson learned, then you need to evaluate whether the subject you’re writing about is a well-known concept. If it is, then your content doesn’t need to provide a detailed overview before getting into the guts of the story. If you’re writing a blog targeting Java developers, you don’t need to explain what the JVM is.

Next you’ll want to think about the best format for your content. Although there are many types of writing out there, it might be easiest to think in terms of two main types: longer-form, formal articles and more casual pieces like blog posts. For more casual writing, such as a post on your personal blog, it’s best to keep it short and high-level and focus on a specific topic, like this one that shows how to run Elastic Cloud on Kubernetes from Azure. Formal articles are usually longer, provide deeper context, and may explore different facets of a topic or multiple topics, like this one about benchmarking and sizing Elasticsearch clusters for logs and metrics.

If you’re writing about a journey, then you might want to write a longer piece, because you’ll need to provide a good amount of details before jumping into any conclusions. The tone for longer pieces tends to be more educational and scholarly. Use cases and lessons learned can be written in a more informal, blog post style, as they tend to be short and sweet and use a tone that is more laid back and sometimes even witty.

Your unique communication style also plays a key role in your writing. We all have different communication styles and ways of expressing our thoughts. This is a great thing — in fact, it’s part of Elastic's Source Code. So whatever your communication style, please embrace it! The unique way you create emphasis, how you break down concepts into bite-sized chunks, and even your sense of humor is what makes good content. If you’d like to refer to guidelines for how we write at Elastic, feel free to check out our naming guidelines and our writing style guide page.

Finally, make sure to proofread your writing before you publish. This means making sure that the grammar is impeccable and your thoughts are clear. Try reading your writing several times and revisiting problematic areas. If possible, ask a friend to provide feedback as well. Be open to feedback, especially feedback on areas that might be unclear.

We hope that this blog post has helped you to start your journey in contributing written content to the community. If you have any questions about how to contribute, please feel free to reach out to us at contributors@elastic.co.