This article is part of a series on Developer Experience that I’m attempting to start. Developer Experience, or DevX or DX, is a growing area of interest for a lot of organizations. DevX, as its name implies, focuses on the developer/engineer in order to remove friction points, increase automation, and generally allow engineers to focus on writing code that has business value.
One area that experience has shown me requires some attention in the context of DevX is “Inner Source.” For the uninitiated, Inner Source is like Open Source, but it’s only open to those within an organization. This is typical at organizations where all development is the intellectual property (IP) of the company (I’d imagine this is most companies).
As such, there are processes and procedures to follow to allow engineers to provide their code to the Open Source community. This process can be arduous, and if the software doesn’t have broad appeal, then it’s generally not worth it. Instead, engineers will make the software available to everyone in their organization or company where the IP is safe. This is called Inner Source.
The Challenge
In my experience, one of the major challenges for Inner Source is attention to the developer experience. To put a finer point on it, Inner Source, with its more lax processes and procedures, can end up unpolished.
Think of a scenario where you build some piece of software; let’s say it’s a CORS proxy. This project probably started out as a stopgap measure to enable the development of some primary piece of software (unrelated to the proxy). As such, the code is thrown together pretty haphazardly without much attention to the critical components that enable adoption:
- Clean, readable code
- Error handling
- Sensible tests
- Meaningful documentation
- Contribution and code of conduct guides
- A “Getting Started” guide
- A “Quick Start” process
As a developer, you may think, “well, it’s Inner Source, and the code is right there; anyone can read it. It’s self-documenting!” And, as a developer, you’d be wrong.
The Guessing Game
When you throw a piece of software over the wall and say, “figure it out,” you’re putting an undue burden on any interested parties. You’re effectively saying, “I can’t be bothered to document this, so everyone that tries to use it needs to start from scratch.
Do you see the problem (hint: think efficiency)? You’ve created some tooling that’s meant to help other developers skip some steps in the development, but you’ve just replaced the steps with a different set.
As an analogy, consider a movie streaming service. This service has thousands of titles ranging from feature-length movies to episodic series to documentaries and everything in between. You, as a customer, are browsing the collection and see some unfamiliar titles. The cover art piques your interest, so you want to know more before sinking your time into a two-hour film. What would you do?
Under normal circumstances, I would assume you would look for a trailer – a short introduction to the film which gives you an overview of what to expect. Imagine instead if the streaming service made you download a ten-page PDF that provided the synopsis. In order to know whether you want to invest your time in the film, you need to invest your time to find out if it’s worth investing your time.
This is the same nonsensical process that can happen with poorly curated Inner Source projects.
A Better Approach
If you want folks to use your software (otherwise, why did you Inner Source it?) then provide them with a “trailer.” Most high-quality projects will have a “Quick Start” or “Getting Started” section on their landing page. This allows developers to try it before they commit to it.
I would go as far as to say there should be a maximum of one or two steps required to run some demonstration of the software, assuming a standard developer setup. The advent of containers has made this even easier – just spin up an OCI image with everything preconfigured for a demo. Providing this “quick look” or “trailer” helps everyone understand what the software does and allows them to start using it right away.
Let’s expand upon that list from earlier with a non-exhaustive checklist for releasing code as “Inner Source”:
- Clean, readable code
- Robust error handling
- Sufficient tests (these act as usage examples as well, when done correctly)
- Clear documentation (including diagrams if it helps explain the operation)
- A “Getting Started” guide
- A “Quick Start” process
- Contribution and code of conduct guides (to set expectations)
Help Me Help You
In general, if your goal is to help improve the efficiency of developers and improve the developer experience, then thought and craftsmanship must be imbued in the software and its release to a wider audience.
Don’t assume that everyone that may want to use the software has the same domain knowledge that you do or that they have the time to read every line of code to understand its operation. Don’t be the streaming service that makes you read PDFs instead of providing trailers.
Most importantly, though, don’t stop promoting your software to Inner Source. There’s a huge productivity gain by avoiding duplication of effort as long as enough care and attention are given to the project.
