Forem: Yalla, DevRel

Beyond Hacktoberfest: The Pitfalls of Rushing to Open Source

Ben Greenberg — Thu, 05 Oct 2023 19:27:39 +0000

It's the month of Hacktoberfest where thousands of people around the globe engage in open source projects. A lot of those folks will be first time open source contributors, and many others will be casual contributors to open source projects. It's a celebration of all things open source, so perhaps it's not a good time to talk about how open source is not always the answer? On the contrary, now is the perfect time.

A popular sentiment amongst open source enthusiasts is that by open sourcing a product, you will almost immediately begin to see positive results! Positive results in what specifically? Well, increased engagement from developers, more trust in your product from technically minded people, and all of this will lead to more usage overall.

This is not wrong at its face at all. In fact, there is a lot of truth to that perspective. Eyar Zilberman in a podcast episode from 2022 outlined all the reasons why his company, Datree, chose to open source their products from day one. Many of those reasons are the same as what you read above. However, he does also call out the need to get it right.

Because, the fact of the matter is, an open source project on GitHub without the proper structure might be worse for your future success than not open sourcing it all.

In my time as a maintainer for several open source projects over the years for different companies, I've seen firsthand both the benefits and the drawbacks to open sourcing, and it all comes down to your readiness to build the scaffolding to enable external contributors success in the project, and commitment to ongoing support of the project.

Let's talk about what each area entails.

An open source project without the right structure around it is like hosting a dinner party for your friends in a house missing anything to sit on, any plates or cutlery to dine with, and just serving them a piece of lettuce in their hands.

They may enjoy eating that one piece of lettuce, but can you really call that a dinner party?

What structures must be in place for an open source project to be considered welcoming?

Make sure you have the following:

README
License
Code of Conduct
Contributing Guidelines

Extra bonus points if you also have:

Automated testing in your CI/CD pipeline
Well defined tags to define new issues and pull requests

Now, having any or all of these things, but they are done poorly does not count. Each item in the list needs to be completed well and regularly maintained for accuracy.

How do you start even knowing where to begin in producing all these elements that make up a well defined structure to house your open source product?

You can browse and learn from free resources online on how to make a good README, the GitHub Wiki on READMEs, freeCodeCamp's article on open source licenses, the GitHub Wiki on Contributing Guides, and a lot more.

After reading these articles and others you find, make sure to incorporate their learnings into your project and produce well defined, actionable (in the case of the Code of Conduct), and accurate resources.

That's only half the picture, though. Once you have defined all the structure, all the scaffolding around it, you also need to ensure that you have the resources and commitment to be responsive in your project once you open source it.

Have you ever raised an issue in a project's open source repository and waited weeks, perhaps longer, to hear a response? Maybe you never heard back at all? Was this a project you relied upon in your own work? How did that make you feel?

An open source repository that has become a ghost town will eventually cause your actual product to become a part of that ghost town as well.

What are the service level expectations (SLEs) for your open source repository?

Define in advance answers to questions like:

How long a new issue can go before it has any kind of response?
How long a pull request from the community can go before its reviewed?
What is the expected time to resolve an open issue?

Make sure to designate people on your team with the specific responsibility of doing this community work and hold them accountable to it.

Automation can help you get some of the way. You can build bots with GitHub Actions to be the first responders to new issues and pull requests. For example, I recently built this one for a developer champions program whenever someone submits a self-nomination for hero status in the program. Yet, you cannot rely on those automations exclusively. You will still need people for the follow-up and the relationship management in the repository.

Does all of this feel like too much for your current staffing resources? If you're feeling overwhelmed, don't be! A lot of this work falls under the discipline of developer relations (DevRel) and an experienced developer relations engineer or developer advocate on your team can go a long way in working towards this.

Additionally, many consulting firms nowadays offer DevRel as a Service (DRaaS) and can provide short and medium-term solutions to build out the structure and provide ongoing support, including Yalla, DevRel.

Regardless of the path you choose, make sure to think things through and be intentional when embarking on open sourcing your product. Doing it the right way can be a remarkable boost in developer engagement and excitement, but doing it poorly and not thought out can produce the opposite results.

Code Not Prose: Why Your Devs Shouldn’t Write the Docs

Ben Greenberg — Tue, 03 Oct 2023 18:27:09 +0000

Why wouldn't a company choose to have the developers who write the code also write the documentation for that code? Is it not the case that the ones who write the code are the ones best equipped to explain it to others?

The answer is an unequivocal and absolute no. The developers who spend countless hours writing the code, should absolutely not be the ones tasked with producing the final documentation for it. This will create a definitively poorer experience for the users who need to work with the product/tool/SDK they have built.

To understand why that is the case we need to understand two things:

The cognitive bias known as the curse of expertise
The distinct profession of technical writing

These two aspects combined make a compelling case to keep the core developers of a product as initial producers of the docs, at the most, but never the final authors, and certainly never the arbiters of what is a good documentation experience for others.

In 1990 a researcher at Stanford University asked random participants in a study to assume the role of either "tapper" or "listener". The tapper was tasked with tapping out on the table the popular Happy Birthday song, while the listener was asked to identify the song from the taps.

How often do you think people guessed the song correctly?

2.5% of the time.

At what rate do you think the tappers assumed the listeners would be able to get the song before the experiment began?

50% of the time.

Think about that for a moment. How could there possibly have been such a wide disparity between the estimation of success and the actual results?

Enter stage left the cognitive bias of the curse of knowledge or the curse of expertise. Once someone knows something, they are cursed (hence, the name of the bias) with that knowledge and are challenged from being able to imagine the difficulty others have in assimilating that information.

What does this have to do with writing good documentation? Well, everything!

Those who are tasked with writing the codebase are undoubtedly the single greatest experts in that codebase. They know every class and every method. They understand why they made an odd choice in that one bit, or why they chose to use a certain naming convention in another bit. This knowledge came through the hard and exhausting process of iterating on the code over and over again until it was ready to be shipped. They earned that knowledge.

Yet, now that they have gone through that process, their ability to empathize with others who are new to it is challenged. Not all the time, there are those who can overcome that cognitive bias, but certainly most of the time.

This challenged perspective leads to incomplete docs because they assume a lot of knowledge on behalf of the reader.

If you have ever used docs to build with an SDK or a library and experienced the frustration of needing to spend hours to figure out the one part that wasn't mentioned in the step-by-step guide, you have most likely experienced the result of this bias in action.

Docs must be written by someone other than the person who wrote the code.

The person who needs to learn the codebase in order to write the docs can model that learning in the documentation journey they craft. The person who comes to the codebase not from the hard earned place of the code author, but from the place of "user #0" will make sure all the bases are covered, and a step is not missing in any guide they produce.

This is one half of why the developers should not be tasked with creating the final documentation experience. The second reason is because technical writing is not a subsidiary field of software development, and its discipline and practice cannot be inferred because someone happens to also be an excellent software developer.

Technical writing is its own discipline and expertise.

Documentation is a learning journey for users, both docs for fellow developers and non-technical folks alike. This journey should not be crafted haphazardly and with no grounding in any recommendations from the field or learnings from peers in the space.

An excellent software developer can be an excellent technical writer, and vice versa. However, that excellence does not happen just because they are a great software developer and by virtue of their skill in one area. As a person learned to write code, a person can learn to write prose.

All too often, engineering teams are given free reign to own the end-user experience of the products they code, whether a framework, an SDK, an extension, a library or anything else. Good leadership helps eager engineers know their limits, and provides avenues to train developers excited to contribute to the user learning journey.

This is not to say that developers have no role in the docs. That is also absolutely not true.

The developers should be consulted to ensure accuracy, any challenges the writers experience in using the product while producing the docs can be fed back to product and/or engineering, and devs should be encouraged to produce quality code comments that can be the kernel seed for documentation. There are even opportunities for developers to write first iterations of docs and then hand them over to those in the discipline of technical writing for refinement and review.

What about small teams without the resources for this clean division of labor?

In that case, of course devs must write the docs as there is no one else to do so. While doing so, it is important to be aware of the cognitive bias of the curse of knowledge, and to spend some time studying from the technical writing industry. There is a wealth of knowledge freely available online for people entering into technical writing.

It's also imperative to mention the benefit of cultivating a robust open source culture. Whether your product is open source or not, your docs and the docs platform certainly can be!

Similar challenges toward quality documentation exist when soliciting community contributions as when engineers are writing the docs. However, for the most part, you are working with an audience of people who are your users, and thus are encountering the product not from a perspective tinted with the curse of expertise. They are your users #0, #1, #2, and onward.

Your docs are for many of your users the first entry point into your product. They are meant to be a journey that takes a user from rookie to expert and all the steps in between. It can be tempting to leave this fundamentally important resource in the hands of your experts, the developers who wrote the product, but doing so, unless you have no other choice, is often a mistake.

Whether through community contributions, working towards a budget that enables hiring people in the discipline of technical writing, providing the skills for developers who want to write to be able to do so, or some combination of all of the above, do not neglect your docs and give them the professionalism and respect they need to help your users succeed.