Most community managers spend hours each week answering the same questions over and over. You might find yourself repeating instructions for how to join a project, what the process for submitting an event proposal is, or who to contact for a specific problem because "everyone just knows" how things work. The issue is that the information isn't easy to find or understand when your community members need it most.

Effective documentation is the unsung hero of a thriving community. In this tutorial, you will learn how to create documentation that genuinely serves your tech community. You will discover proven techniques for organizing information, writing clear instructions, and building systems that work for both newcomers and experienced contributors.

Table of Contents

• Why Community Documentation Often Falls Short

• Core Principles for Effective Community Documentation

• How to Know Who You're Writing For

• How to Organize Information for Easy Access

• How to Write Instructions That People Can Actually Follow

• Essential Documentation Every Tech Community Needs

• How to Create a New Member Onboarding Guide

• The Community Operating Procedures Handbook

• The Event Planning Handbook

• The Community Guidelines and Behavioral Expectations Handbook

• How to Test Whether Your Documentation Works

• How to Observe How People Actually Use Information

• How to Ask Targeted Questions for Improvement

• How to Monitor Community Health Indicators

• How to Maintain Documentation as Your Community Evolves

• How to Schedule Regular Review Cycles

• How to Create Systems for Community Input

• How to Build Documentation Updates into Regular Workflows

• How to Create a Culture of Clear Communication

• How to Model Excellent Communication Practices

• How to Integrate Clarity into Decision-Making

• How to Recognize Clear Communication

• Conclusion

Prerequisites

To get the most from this tutorial, you should have:

• Experience participating in or managing tech communities.

• Responsibility for creating processes or guidelines that others need to follow.

• Access to community platforms like Slack, Discord, or similar communication tools.

No formal writing experience is required. This guide focuses on practical approaches that work in community settings.

Why Community Documentation Often Falls Short

Documentation often fails because it is created for the wrong audience or stored in a way that makes it difficult to find. A common pitfall is creating documentation that is too technical or formal, using jargon that is not understood by new members. Another issue is that documentation is often a one-time effort, not a living resource. When processes or team members change, the documentation becomes outdated and unreliable, causing people to abandon it entirely.

Core Principles for Effective Community Documentation

Strong community documentation is built on four key principles that make information genuinely useful rather than just comprehensive.

How to Know Who You're Writing For

Different community members need different information depending on their experience level and involvement goals. Consider these main audiences:

• New members who are exploring how to participate.

• Active participants looking for specific opportunities or information.

• Volunteers needing clear instructions for their responsibilities.

• Organizers requiring detailed procedures and decision-making guidelines.

How to Organize Information for Easy Access

The way you structure information is just as important as the information itself. Good documentation anticipates a user's needs, allowing them to find what they are looking for without digging through endless pages.

A well-organized documentation hub should mirror your community's journey. Start with high-level, introductory information and then branch out into more specific, detailed guides. For example, a newcomer should see a clear pathway to finding a welcome guide, while an experienced volunteer should be able to jump directly to a detailed event checklist.

Think about using a central location that is easy to access, such as a dedicated channel, a pinned post in your community platform, or a simple, single-page website. Use subheadings and bullet points to break down long sections of text, making the content scannable and digestible.

How to Write Instructions That People Can Actually Follow

Clear instructions are the bedrock of effective documentation. When you write a guide, imagine you are sitting with a new volunteer, talking them through a task step-by-step. Use active voice and simple, direct language. For example, instead of writing "The event registration form should be created," write "Create the event registration form."

Use numbered lists to guide readers through a process in a logical order. You can use screenshots and diagrams to illustrate a point, but make sure they are clear and easy to understand. For instance, a screenshot of a community's Standard Operating Procedure (SOP) document can help a new team member visualize their tasks.

Essential Documentation Every Tech Community Needs

Different types of documentation serve different purposes in community management. Here are the most important ones to prioritize.

How to Create a New Member Onboarding Guide

Your onboarding documentation should help new members feel welcome and find their first meaningful way to participate. Effective onboarding includes:

• A welcome message explaining community values and culture.

• A quick overview of how to access and use community platforms.

• Immediate ways to get involved that match different comfort levels.

• A community calendar highlighting upcoming opportunities.

• Clear contact information for getting help.

The Community Operating Procedures Handbook

Standard procedures ensure consistent experiences regardless of which team member handles a situation. As community management expert Rosemary O'Neill notes:

"Clear processes are not about bureaucracy – they are about creating predictable, positive experiences that let community members focus on connection rather than confusion."

Comprehensive community procedures should address:

• Team Structure and Operations: Community mission statement and core values, team roles with clear responsibility boundaries, decision-making processes and approval workflows, communication protocols for different situations.

• Member Experience Management: Application review standards and timeline expectations, new member welcome sequence with multiple touchpoints, engagement strategies including regular check-ins and recognition programs, pathway documentation for members to increase involvement, feedback collection methods and response protocols, professional offboarding process for departing members.

• Community Building and Growth: Content creation guidelines and approval processes, partnership evaluation criteria with other organizations, volunteer recruitment strategies and management systems, leadership development opportunities and requirements.

• Event and Program Management: Event planning workflows from initial concept to post-event review, speaker recruitment, vetting, and coordination procedures; registration management and attendee communication templates, technical requirements and setup procedures for different event formats, post-event evaluation and improvement documentation.

• Community Health and Safety: Conflict resolution procedures with clear escalation paths, community guideline enforcement protocols and consequences, crisis communication plans and emergency contacts, member well-being resources and support systems.

• Evaluation and Improvement: Community health metrics and regular assessment schedules, member satisfaction measurement and analysis methods, growth tracking systems and reporting requirements, quarterly review processes and improvement planning.

The Event Planning Handbook

Events often drive community engagement and growth. Your event documentation should enable teams to create successful experiences consistently. Organize event documentation by timeline:

• 6-8 weeks prior: Initial planning, venue booking, speaker outreach.

• 4-6 weeks prior: Registration setup, marketing launch, logistics confirmation.

• 2-4 weeks prior: Final details, volunteer coordination, attendee communication.

• Week of event: Setup procedures, team briefings, backup plans.

• Event day: Detailed checklists for setup, execution, and wrap-up.

• Post-event: Follow-up tasks, feedback collection, documentation updates.

The Community Guidelines and Behavioral Expectations Handbook

Community guidelines should clearly communicate expectations while reflecting your community's specific culture and values. Effective community guidelines include:

• Specific behavioral expectations with concrete examples.

• Clear consequences that focus on community repair and learning.

• Accessible reporting procedures for concerns or conflicts.

• Resolution processes that prioritize healing and growth.

• Recognition systems for positive community contributions.

How to Test Whether Your Documentation Works

Creating documentation is only the first step. You need to verify that it actually helps people succeed in your community.

How to Observe How People Actually Use Information

The most valuable feedback comes from watching interactions between community members and your documentation. Observation methods:

• Ask new volunteers to follow your procedures while you watch (without providing extra help).

• Monitor community channels for repeated questions that suggest documentation gaps.

• Track completion rates for multi-step processes.

• Pay attention to member feedback about confusing or particularly helpful resources.

How to Ask Targeted Questions for Improvement

Generic feedback does not provide enough detail for meaningful improvements. Ask specific questions that reveal actual pain points. Useful feedback questions:

• "At what point did you feel unsure about what to do next?"

• "What information were you looking for that you could not easily find?"

• "If you were teaching this process to someone else, what would you explain differently?"

• "What would have made this experience smoother or more welcoming?"

How to Monitor Community Health Indicators

Good documentation should contribute to overall community sustainability and member satisfaction. Signs that documentation is working:

• Fewer repetitive questions in community channels.

• Higher volunteer retention and satisfaction scores.

• Faster integration of new members into community activities.

• More consistent execution of events and programs.

• Reduced administrative burden on community organizers.

How to Maintain Documentation as Your Community Evolves

Documentation requires ongoing attention to remain useful as your community grows and changes.

How to Schedule Regular Review Cycles

Establish predictable times for updating and improving your documentation:

• Monthly reviews of frequently-used resources like onboarding materials.

• Quarterly comprehensive reviews following major events or program cycles.

• Annual documentation audits to remove outdated information and improve organization.

• Immediate updates when processes change or new information becomes available.

How to Create Systems for Community Input

Make it easy for community members to suggest improvements and contribute updates. Simple contribution methods:

• Feedback forms or shared documents for quick suggestions.

• Regular "documentation improvement" sessions during community meetings.

• Recognition programs for members who contribute helpful updates.

• Clear guidelines explaining how community members can suggest or make changes.

How to Build Documentation Updates into Regular Workflows

Instead of treating documentation as separate work, integrate updates into existing community management processes:

• Include documentation reviews in event planning checklists.

• Assign specific documentation responsibilities to team members.

• Make documentation accuracy part of program evaluation processes.

• Train multiple people to update and maintain critical resources.

How to Create a Culture of Clear Communication

The most effective community documentation happens when your entire team values clarity and considers member experience in every decision.

How to Model Excellent Communication Practices

As a community leader, your communication style influences how everyone else approaches sharing information. Ways to model good documentation habits:

• Always include context when making announcements or giving instructions.

• Follow up on frequently asked questions with documentation improvements.

• Acknowledge and appreciate team members who create helpful resources.

• Treat documentation work as valuable community contribution, not administrative overhead.

How to Integrate Clarity into Decision-Making

Make "Will this be clear to community members?" a standard question in your planning processes. Consider documentation impact when:

• Launching new programs or changing existing procedures.

• Planning events or community initiatives.

• Onboarding new team members or volunteers.

• Responding to community feedback and implementing improvements.

How to Recognize Clear Communication

When community members create helpful resources, explain things well, or improve existing documentation, make sure their contribution is acknowledged and valued. This recognition encourages others to consider community accessibility and take ownership of shared information resources.

Conclusion

Effective community documentation is not about perfect writing or exhaustive detail. It is about understanding what your community members need and creating clear paths for them to succeed.

You've learned how to organize information around member goals, write instructions that prevent confusion, and build systems that keep documentation relevant as your community grows. Most importantly, you've discovered how to promote a culture where clear communication is valued and community accessibility becomes everyone's responsibility.

Remember, this key principle: good community documentation is measured by member success and community health, not by volume or technical perfection. When new members can easily find ways to get involved, volunteers feel confident in their roles, and your community operates smoothly without requiring constant intervention, your documentation is fulfilling its purpose.

Start with one small improvement. Choose a process that generates frequent questions, apply these techniques, and observe the impact on your community's experience. Each improvement is a step toward building a truly sustainable, welcoming tech community where everyone can contribute effectively.

You can also connect with me on LinkedIn, X (Twitter) and Medium. If you made it to the end of this tutorial, thanks for reading!

Between the three of them, the co-founders of Orbit have decades of experience in engineering and developer relations, building products at companies such as Accenture, Algolia, Apple and Keen.io. After launching Orbit, they spent the last year talking with people in the DevRel space about proving the value of DevRel.

January is a common time for executives to ask what kind of investments they should make in developer relations including what hires to make, and what the business case is.

After Orbit joined Heavybit last month, I sat down with Josh, Patrick, and Dustin to talk about their approach to DevRel, from partnerships and promotions to outsourcing and metrics.

Table of Contents

• What are the biggest missteps companies make when it comes to DevRel?
• What parts of DevRel should companies outsource?
• How do you leverage partnerships?
• How can DevRel partner with business development?
• How do you balance creation vs promotion?
• Who in DevRel would you like to call out?

Q: What are the biggest missteps companies make when it comes to DevRel?

One big mistake is trying to hire a developer advocate before the company has learned to do at least a little DevRel on their own. In the consulting world, companies would come to us and say "we’re ready to hire, we just need help writing a job description and sourcing candidates." At that point, sometimes these companies had not given a talk or created developer-facing content.

By contrast, at some companies, every engineer is doing some aspect of DevRel from the time the company starts, like giving talks and contributing to projects. If a company tries to hire a DevRel-specific role but doesn’t have experience in that area, it’s going to be difficult for them to be successful.

Companies and teams have to define their internal expectations for DevRel. It’s common to read a job description for DevRel that isn't focused -- it could span dozens of key activities! If a company has done DevRel themselves, they typically surface a more focused job description. For example, do they see this role on the road giving talks, or being an internal advocate? We want to help companies avoid writing job descriptions that are “be all the things.”

Q: What parts of DevRel should companies keep in-house, versus outsourcing?

It depends on which parts of the DevRel process you need help with.

On one hand, your DevRel person who has the touch points with the community -- that person should live and breathe inside your organization and embodies the organization's culture. If a company has contracted with an outside firm, you may not get the same experience talking to them, versus talking with employees embedded in the culture of the company.

If your advocate echoes your values, it leads to a better developer experience. That’s a risk when making a contract hire, especially on the community side. I’ve seen contractors do social media for a company’s developer community and it all goes wrong — it’s mind blowing why companies do this with little training and oversight.

However, if you’re working solely on content, tutorials, etc, that can be a great place for outside help, since there will be other people in the organization that are reviewing the content to make sure it falls in line with the company's positioning and values.

We consulted for the past year so we have some bias here, but using outside companies to generate strategic, third-party content can give you a lot of leverage. They can lean on your internal teams to amplify the content and bring the messages to market. We’ve done this a number of times with different companies -- it makes developer advocates inside the company feel like superheroes because they have a lot of great content that they can bring out and share with the community.

Q: How can we in developer relations leverage internal partnerships to increase our reach and effectiveness?

We think partnerships can be one of the most impactful parts of a successful DevRel strategy. A single advocate or DevRel team serves as a force multiplier across the entire company. The internal impacts of a team that’s working well are enormous when multiplied across the entire company.

We can give tons of examples, but to focus on a few: in marketing, DevRel can help keep the brand voice true to the developer personality. In return, marketing helps DevRel be more data driven, driving value in both directions.

In larger companies, there is an opportunity to bring the voice of the developer into internal conversations. You can imagine bringing stories from the field into the walls of the building and giving the company a few into how developers interact with your product.

Historically there has been somewhat of a mismatch between teams like sales and marketing and community teams like DevRel. Often this is based on a mismatch in funnels.

DevRel can evangelize alternate models of measuring impact of community instead of the standard model of pushing people into a funnel and measuring purchasing events. The Orbit model allows you to rewire the way companies think about community, not just a standard marketing funnel, but allowing you to create metrics around your community efforts.

We also see DevRel and Sales working well together — historically, this isn’t always the case! We've seen that they can be very collaborative and complementary when there is clear communication.

In large organizations it's rad to see individual developers participating in the community -- if a company's developers are contributing to your project, that’s a strong signal that the company may be interested in a commercial relationship.

From a sales perspective, you probably don't want an SDR emailing those developers, but the SDR would love to have feedback about that developer’s activity that they could reference when calling the developer’s manager. Of course, that requires data and tooling on the back-end to surface that information, and that’s something we see a lot of companies moving towards in 2020.

We actually wrote a whole series for Heavybit covering different tactics for internal collaboration.

Q: How about business development -- where are the opportunities for developer relations teams to partner there?

Agency partnerships come to mind pretty quickly. For companies with a developer-focused platform, part of the BizDev model is to partner with agencies who can build the platform into products for clients. Algolia had relationships with agencies implementing all the different ecommerce and CMS platforms.

Creating formal partnerships with these companies can be useful for BizDev but can also help your DevRel program by encouraging the agency developers to be involved in the technology ecosystem.

DevRel can also partner with complementary companies and projects. This can keep things fresh and make sure you’re not talking too much about yourself and your products -- you're bringing some fresh voices into the conversation.

Q: Where do you draw the line on creating new assets, such as content and talks, and promoting those assets? Should 100% of your DevRel budget go to creation, 100% to publicity, or somewhere in between?

Looking at DevRel as a whole, generally we think that more re-use would be smart. Writing a new presentation each time you give a talk is very expensive in terms of effort and mental energy.

Many developer advocates are hesitant to re-use material, but they shouldn’t be -- there are millions of developers out there who haven’t seen your presentation before. If stand-up comedians can re-use the same jokes for years, you shouldn’t have to worry about giving the same talk twice in the same city.

One trick I have: give talks to engineers inside the company, and then let the engineers give that talk elsewhere. Make your assets and presentations so that others can re-use the deck and script. That’s a nice way to get engagement in the DevRel effort from others in the organization — three months later, someone is speaking on stage, maybe for the first time.

Often there are engineers inside your company who want to get started getting talks, and as developer advocates who do this multiple times per week, we can facilitate these engineers and also cover more territory. (There are a lot of events I want to speak at, but I can’t be in two places at the same time.)

Q: Is there anybody out there in DevRel who is doing an amazing job, that you’d like to highlight?

• Doron Sherman, VP DevRel at Cloudinary has a great DevRel program
• Stefan Judis at Twilio for being data-driven, he’s got a great approach and dashboard for his content that is pretty impressive
• Tim Berglund and Ale Murray, Confluent team

Thanks to Josh Dzielak, Patrick Woods, and Dustin Larimer for chatting with me about their DevRel experience.

Next Steps:

• Follow Orbit on Twitter
• Check out (literally, you can check it out) the Orbit Model GitHub repo
• Catch up with Orbit's DevRel Blog.

IBM’s $34B acquisition of Red Hat closed last week, underscoring the huge and growing importance of hybrid cloud infrastructure. My colleague Marek Sadowski has become a subject matter expert in containers, Kubernetes and server-side Swift, although he started out as a full stack developer advocate, a robotics startup founder and an entrepreneur.

Marek has 20 years of enterprise consulting experience throughout the USA, Europe, Japan, Middle East and Africa, and he pioneered in research on VR goggles for the virtual reality system to control robots on Mars during his time at NASA. After founding a robotics startup, Marek came to work at IBM. I talked to him about his experience in DevOps advocacy.

Table of Contents

• How DevOps advocacy different from API/app advocacy?
• How do you focus on the DevRel community?
• What have you changed when moving to DevOps DevRel?
• How do you get developers to see Swift as server-side?
• How did you get into DevRel?

Q: One of your focus areas in DevRel is containers. How is advocating for a DevOps technology different than advocating for an API or application?

Good question. When working with containers, engineers think more in terms of the plumbing and ideas of DevOps and the ease of expanding your infrastructure footprint. In contrast, when you talk about APIs, you try to make application development the center of gravity for the discussion.

When discussing APIs with developers, you talk about how one could -- in a robust way -- consume the API. Let’s take the IBM Watson API as an example: our team will talk about how you can create and run SDKs for developers to consume APIs in their own language, for example, Swift (for mobile) or Java (for enterprise.) You’d look at the consumer of your API and discuss how you can produce the API, protect yourself and do the billing.

Getting back to containers: when discussing container technology, you speak more about plumbing of the cloud. How do you manage containers? Expand them? Manage their workloads? Deliver and test new versions?

It quickly becomes apparent that these are two separate concepts. Containerization deals with how your backend is working and proper maintenance of your application, which attracts people from a DevOps background. When you talk about APIs, that’s a completely different story. Your thought paradigm changes to the point of view of the consumer: How does the consumer find the API? How can developers consume the API?

I speak at conferences on both subjects areas. I’ve found that people who develop applications are more interested in the look and feel and developer experience of the application, whereas with containers it’s more about backend, load balancing, and seeing issues from a system administrator’s perspective.

Q: Many people are familiar with DevRel with a focus on software engineers, but DevOps is a different community entirely. How do you focus on that community?

There is a division — everybody is interested in new things like Kubernetes and Docker, but not too many will want to perfect their skills to the point that it’s their daily job. So many developers want to know how to spin up a container and a service inside the container, put it in their resume and be done with it. Developers may be interested because it’s fashionable or it’s a buzzword. However, you can find a lot of people who are running services in containers and have specific questions: sysadmins who want to monitor containers and assure security, load balancing, and other aspects of administration. It’s a completely different audience from developers who consume APIs and create a cool web application. They are two different communities, and you have to give each community different content.

For example, in a hackathon it’s very difficult to create large deployments in containers. It’s an optimization of development and operations more than application coding.

Q: How have you had to change your approach to DevRel when moving to DevOps advocacy?

Previously when I ran workshops focused on application developers, they’ll usually have a few goals: understand our API, consume data from API endpoints and create a simple “Hello World” types of applications. Developers in these workshops will ask questions about high-level ways of architecting applications, e.g. with Watson, in mobile applications or web applications, or a chain of processes.

On the contrary, when I speak about DevOps and containers, developers in the audience want to spin up the services, see how they scale up and scale down, investigate how the services behaving when something is failing and how to ameliorate security issues. It’s a completely different approach. They are not interested in building something new, they want to perfect their approach to deployment.

An analogy I can give to people new to this field: it’s like inviting a painter and a plumber to a party. They both do similar things, yet the painter wants to make a painting that you can hang on the wall, and the plumber will rarely speak about the type of piping he’s using inside your walls. Both are doing something in your house, but the painter is thinking about the people they will attract and the paint (our APIs) to ensure a pleasant viewing experience, while the plumber just wants to get the job done and never touch it again. The plumbers want to make changes as rarely as possible and focus on stability, the painter wants to create more new paintings. They have different approaches based on their different goals.

Q: You also give talks on Swift, specifically on the server side. Most people know Swift from the iOS development side, but why is it useful on the server? How do you get developers to think of it as a server language?

Server-side Swift is a relatively new development. I compare the current state of server-side Swift to where Java was twenty-four years ago. In 1996 I started writing a server-side application using Java -- it was a novel concept at that time! The same thing is happening now with Swift, as developers are moving the Swift language to the server. There are a lot of reasons why; one of the simplest is that you write in the same language on the server as you do for your mobile app, and in that way you can use the same data constructs, thought processes and personnel resources on both systems. You don’t need different systems or frameworks to talk to the database or the cloud.

Every mobile app nowadays asks you to connect to the internet for AI, messaging and social media. Even simple games allow you to exchange information or have a conversation with people all over the world. If your app and back-end are written in one language like Swift, it makes these data exchanges simple and transparent.

Some people are saying Swift is a fashionable language to learn. Since you have the option to write apps in Java or JavaScript, you can also write them in Swift. Swift has now been open-sourced by Apple, similar to the way Sun opened up Java. You can now write applications in the cloud or on any platform. For example, OpenWhisk allows you to write event-based Swift functions in the cloud without any DevOps code.

With Swift, developers are attracted to the beauty of the language and the ability to write one language from mobile to cloud to make your application better and easier to maintain. You can enjoy writing in your language of choice and expand the capabilities of the environment you love. If you are an iOS developer, maybe you can become a full-stack developer, and developers love the story that they can become something more and participate in the full stack development process.

Q: How did you get into developer relations?

I had just come to the United States from Poland as the founder of a startup, and the purpose of the move was to expand my company. They say that 99% of startups don’t succeed right away, and founders often need to bootstrap while in an existing job. I was told that working in the cloud is the key factor in a lot of industries, but I had little exposure to those technologies. On the other hand, I had built up skills talking to investors, and as an entrepreneur, I was able to understand what was important to startups. I also had a robust background in Java development and different IT technologies — I had a career as an architect supporting banks and other enterprises EMEA as a Java professional, demonstrating systems to customers.

There was an opening for a mobile-first developer advocate, and despite having no mobile or cloud experience, I convinced the interviewer that I was the perfect candidate due to my ease of speaking with developers and presenting technical subjects in an accessible manner. I enjoy explaining complex topics in a simple way through demos and example projects.

My hiring manager asked me to build a small mobile app as an employment test, which connected to IBM Cloud to exchange information between the user and a backend. I enjoyed the task and found I was good at it! After two years, I migrated to more cloud technologies and more and more IBM APIs. Eventually I started to find interest in Kubernetes and containers, and I realized containers are a field with amazing growth potential.

I must say, the thing that attracted me the most to DevRel was the opportunity to learn and convey new technologies to developers out there, and use my talent for explaining complex things in a straightforward manner.

Next Steps:

• Follow Marek on Twitter
• See Marek speak at an upcoming IBM Developer SF Meetup

I'm interviewing my colleague Lennart Frantzell, a fellow developer advocate on the IBM Developer San Francisco team. Inside IBM, Lennart focuses on one of our most technically in-depth communities: Blockchain.

Q: Your developer advocacy efforts focus on projects with large codebases and technical architectures that requires developers to adapt their mental models. Can you tell us about them?

When I came to Silicon Valley in the late 80s I worked on one of the most exciting projects imaginable, Expert Systems, the precursor to today's AI systems and IBM's Watson project. I spend four years in Menlo Park in the childhood of Silicon Valley creating language compilers with built-in AI capabilities. As often with leading-edge technology, we didn't quite make it. Fortunately I then had the opportunity to work on a team in IBM's Silicon Valley Lab in southern San Jose that took prototypes from IBM Research and productized them. From there I moved to Object Oriented systems and have really always worked on advanced software systems. Some of which succeeded but many of which did not. Just like in the start-up world.

Q: How did you get started with programming?

Originally I was majoring in Asian Studies in Sweden and I received my doctorate from the University of Stockholm. After graduation, I realized that there were no jobs in my chosen field, and I began to take an interest in computers. I took a few courses and landed a job in the IT department of the food chain Shoprite on the East Coast of the US. Two years later IBM was advertising for a job for something called the Series/1 minicomputer, which we used at Shoprite. I was lucky to be accepted and spent the next four years writing assembler code that automated telephone switches in Seattle, which I fell in love with. And which is the reason that my oldest son with his family now lives and works in Seattle.

IBM Series/1 Minicomputer

Q: How did you make the transition from programmer to developer advocate?

I have always loved programming but I have also liked working with people, and when I got the opportunity to jump over to one of IBM's Innovation Centers and work with business partners I didn't hesitate.

After a few years this led me to Developer Advocacy which is really great because one meets so many developers and start ups from various geographies and countries with their own perspective on technology.

Q: How do you find that advocacy for deep technical projects differs from developer advocacy in general?

IT technology is suddenly eating the world as Marc Andreessen has pointed out. It is no longer a peripheral technology but changing society all around us.

One compelling example is AI, with image recognition and facial recognition. We have made amazing strides with increased image recognition capabilities, but it turns out there is a flip side to these advances: do we really want AI-systems that can trace our every step. This is something that we as developer advocates can highlight and make people and ourselves aware of.

There is code but code also has a social impact, both good but also from time to time negative.

I enjoy putting together events that focus both on the technical but also on the social aspects of technology. I enjoy looking at the big picture, and it's exciting to work at a company like IBM that gives me free rein to work with developers and startups and not always follow a specific corporate line.

Q: How do you get introductory programmers interested in a deep or very technical ecosystem?

Start with the impact on society. I get uneasy when I encounter people who may not see the forest for the trees, i.e. the impact their code may have on society.

I should also mention the IBM Code Patterns -- an innovative approach to providing developers with working code around specific themes. They allow us to quickly get developers up and running in areas such as AI, Blockchain or Machine Learning, to name a few areas. Something that makes our job a lot simpler than before and that allows us and the people we talk to to quickly see how new technology is behaving in real life.

Q: What technologies that you’ve worked with are you most excited about?

Blockchain, Machine Learning and AI. These technologies are where the future is, and that are already an important part of our society.

For instance, a self-driving car is something you wouldn’t even imagine a few years ago, and now we’re talking not only about the underlying technology and algorithms, but also the impact on society and the freedom it can bring to people around the world.

Q: Let's talk logistics. What types of events tend to work well for the tech you’re advocating?

Face to face events with between 50 and 100 people present. You must remember that attendees come to these events to mingle. They want to meet people, talk, exchange opinions -- they’re not really interested in listening to us talk for an hour or longer. All information is usually out on the web anyway.

They want to learn and code, sure, but it’s primarily a social event and they want to mingle and get contacts. Being able to read the audience and respond to what they want is an important skill as a developer advocate.

Also, we do a lot of hackathons, which are essentially long-running social events. I love working on hackathons more than almost anything else.

Q: Any best practices in developer advocacy that you’ve been exposed to?

I just went to DevRelCon SF 2019 and you could tell from the presentations that developer advocates as a group are really good at talking to an audience -— especially when they are talking about themselves!

Dana Oshiro from Heavybit gave a great talk at DevRelCon SF 2019. It was very factual, and not specific to developer relations but about different aspects of company fundraising, board dynamics and cashflow that are relevant to advocacy but that many advocates may not be exposed to.

Dana Oshiro speaks at DevRelCon SF 2019

Q: What do you want to learn, and who do you want to meet or partner with?

I want to spend time combining Blockchain, AI, ML and IoT, and see where that will lead. It would also be interesting to spend more time with larger startup companies who are on the way to building enterprise applications — currently, I spend a lot of time with smaller startups and individual developers, but working with larger companies will give you a more holistic view of what companies are trying to build with IBM Cloud-technology, including Blockchain and AI. I’m not working in that space currently but I am hoping to get into it very soon.

To get in touch with Lennart, feel free to reach out on LinkedIn: https://www.linkedin.com/in/lennartfrantzell/

Hazelcast is the leading open source in-memory data grid. It offers a small library that provides a clustering and data distribution platform for Java. We asked Chris Engelbert, Manager of Developer Relations at Hazelcast, to tell us a little bit about their open source community.

Tell us about a little bit about yourself and the Hazelcast community. How did it all begin?

Hazelcast is the leading Open Source In-Memory Data Grid, rendering low latency access and fast calculation easy and fast. In 2005 Hazelcast itself started out of curiousity to find out if distributed data structures and distributed computation has to be complicated. The main driving goal ever since is simplicity.

With each release the project grew and more users and contributors joined our tribe. A lot of people were happy with the common style of support given for open source projects at that time, however some users needed more. In 2009 Hazelcast was founded as a company employing an open source business model, at that time and due to the requests from the community, managing commercial support contracts to an open source project. Basically what everyone else did :-)

I joined the company in late 2013, coming from the user / community base, answering questions on Google Groups and being a frequent contributor. I don’t remember if Stackoverflow already was a thing back then. First being part of the core development team, I moved on to Technical Evangelism and finally Developer Relations (as we call our program today) due to my experience in the open source world.

The community / project today has grown to over a 100 external committers and some of them are frequent contributors, some of them are less frequently contributing in terms of pull requests but are actively involved in design discussions, answering questions, speaking at conferences. We engage everyone to join the community forces and support people with swag and other goodies.

What common goals do you have as a community?

To make Hazelcast the most commonly used (and obviously best) In-Memory Data Grid in the market. There are a few competitors, still it is a niche sector. Anyhow our main goal as a community (not only us as a company) is to bring Hazelcast forward, to keep the simplicity approach by heart. We love to engage with people, we love to hear their ideas and we love to work with them.

Last year we started the HEP (Hazelcast Enhancement Proposal) process to engage working with the community even more. Using HEPs we drive the community based development of features or extensions for Hazelcast. People can submit new ideas, they can join others HEPs and in general we try to canalize development in a way to prevent the community and Hazelcast employees working on the same idea / feature independently and in the worst case concurrently. This would result in one solution to be dropped. Apart from that the best results are those that are created together!

What are the main issues discussed in the Hazelcast Gitter channel?

We use multiple Gitter channels. The main channel is used for all kinds of general discussions, questions and open source support. Apart from that we use one Gitter channel for each running HEP (incubator) project to centralize discussion on this feature while it is in discussion or implementation phase. In general everyone is free to join the Gitter channel at https://gitter.im/hazelcast/hazelcast and start discussing about whatever seems interesting to her / him and related to Hazelcast :-)

What are the most important factors that you have taken into account while creating and maintaining the community? What factors contribute to the success of your community?

I guess the key for a strong community is to listen to them. Listen to problems, listen to ideas but also to have an open ear to constructive critics. Users are users and they define how your project is used in the end. Not all of them using it the right or even expected way but those are situations you want to either solve together with them, bringing them back to the right way or where we have to consider if providing a better solution to their use case makes sense. Here again comes the community vs. company into the game. I speak for the community and I fight for every request :-)

On the other hand it’s not enough to just listen but you also need to show responsiveness. You have to react to keep people active, engaged and feel appreciated. Giving reputation to the right people, showing appreciation, as well as reward the most active ones are just a few things that are on the table. When done correctly people come up with talks, writing books, help develop the community together with you. That’s at least my experience.

What are the key challenges that you encounter while managing the community?

I guess it pretty much comes down to the same as my biggest private excitements. Managing all the different channels that developers all around the world want to use. Everybody has his favourite platform and we want the people to feel home when interacting with us.

Gitter has become a main factor in interaction with our community since we started using it about 2 years ago. It is very convenient for the users as you reuse your already existing github user account and it gives direct and fast access to Hazelcast internal developers — and yes they love to interact and chat! Come and try it out! Apart from that the main issue is: my day has only 24h but I would love to work with the community 48h a day!

How do you encourage participants’ commitment and contribution to the community?

We want developers to love Hazelcast, we want them to love it from the bottom of their heart. For the right reasons. Often developers are lazy (I am! You all know the joke that developers automate everything they need at least twice? ;-)) but creative, we want to give them the simplest way to solve their distributed computing / storage problem but also support their creativity with features they really need and love.

Given that we also supply them with everything a loving heart needs, t-shirts, stickers, you know how it works. We love to see people living Hazelcast everyday and we really appreciate every bit that comes from the community. We’re interested in their use cases, we ask them to share their experience with the world, may it speaking at a conference, writing a blog posts, organizing a user group. Whatever they do, we’re here to help them and clear the way whenever possible.

Based on your experience, do you feel that the open source communities have changed and evolved over the past years? If so, how?

I guess open source communities definitely changed. Open source, a couple of years ago, was mainly considered to be okay for startups or smaller companies that had basically no money to spare in software, or for Linux. This has completely changed over the years. Open source moved into the mainstream of software development and made it into the biggest application systems. Even military organizations trust open source solutions for their openness, stability and ease of customization.

Along with the way open source changed, communities followed along. Today open source communities consist of highly skilled, well known and/or extremely engaged people. Some people are even considered the same way as rockstars. Didn’t imagine that while I was in school.

Open source and business is not a contrast anymore, it will change further. Today there is commercial support for almost every bigger open source project and there are people in need of that. Everybody is free and able to pick up an open source project and to provide support. Isn’t it a great software world we’re in? I mean look at Microsoft, yeah! :-)

What advice would you give to someone who wants to start an online open source community from scratch?

Woah, last question, hard question.

Building a community is hard job. You need to be persistent, you need to provide time, I mean a lot of time. Begin with your project, if you find a second or third person, that’s awesome. Build something amazing and people will love what you built.

A good first step is talking about it at conferences, creating awareness. Write about it, make people know it exists. Engage people, help them spreading the word again.

I guess it all comes down to keeping people engaged and love what they do, they’ll love what you do!

Thanks!

P.S. You can easily start your own community Gitter channel here.