By Merlin Carter
“Why do you hate us?”
— An anonymous developer at hackathon
A cautionary tale
When I started my new job as a technical writer, I heard this one anecdote a bunch of times. Basically, the story went something like this:
A developer evangelist had organized a hackathon — he was trying to get developers to use an SDK that my company had just released. But everyone was struggling. The documentation was out of date, confusing, and hard to navigate. People followed the instructions diligently, but they never got the right results.
At some point, a developer approached the evangelist and asked: “Why do you hate us?”
In other words, the evangelist must have known that SDK documentation was so terrible…So why did he invite a whole bunch of developers to build something with it? Was he a sadist?
I’m not sure if the anecdote was exaggerated for dramatic effect…but the melodrama made me laugh. It also made me a little depressed — how could we fail our developer community so badly?
The truth is this enormous multinational company was very late to fully grasp how important developers would be to their success. They neglected documentation quality for too long and are still struggling to catch up. It’s a cautionary tale, and it won’t be my last.
Why should startups prioritize documentation?
At Project A, we mostly work with early-stage startups. So if you’re reading this, you might work for one yourself. I’d understand if my cautionary tale might feel a little irrelevant. Documentation probably isn’t on your mind right now.
After all, if your product is an online shop, you can make do with a few FAQs in your customer support section. Why on earth would you need to think about developer documentation?
Ahhh, but you see, developer documentation includes internal documentation for new developers when they start at your company. It’s what they read to get up and running with your internal tech stack and processes. You do have all that perfectly documented right?….right?
Otherwise, you’d need an expensive senior developer to sit beside them and help them get all the credentials they need, walk them through the tech stack and spend a lot of hours answering questions while not producing any code. And that’s no fun for anybody.
But seriously, I know we all struggle with that kind of documentation. And, of course, new joiners will always need help from their team members. Documentation doesn’t solve everything. I’m just trying to get your attention.
The strategic value of developer documentation
I want to talk about the strategic value of developer documentation in the growth trajectory of a modern digital business. And it really does impact everyone in our portfolio, not just those who are building developer-oriented products.
I’ll get to internal documentation later, but first, let’s start with scenarios where developers are part of your target market. There are a couple of ways where this could play out. Let me give you some examples from our portfolio.
First off, we have Anyline, which produces SDKs and APIs for extremely accurate optical character recognition (OCR). Although Anyline makes free mobile apps, their solution is primarily for large enterprises and government agencies. For example, a German police department integrated Anyline’s technology with its own tools to scan license plates and other forms of identification. So there’s no real “out of the box” product for enterprise customers — developers need to integrate and customize Anyline’s technology for a specific use case.
Next, we have a company like Dixa, a SaaS customer service platform. Unlike Anyline, their target users aren’t developers, they’re customer success teams. Nevertheless, in order to increase its market penetration, Dixa needs to foster an ecosystem of integrations. In this market, the more integrations, the more reach you have. Just look at Zendesk, which has over a thousand apps in its app marketplace. It’s no coincidence that Zendesk has a fantastic developer portal which I’ve used myself to build an in-house Help Center integration.
So we have two cases where developer documentation is a success factor.
If your company is more like Anyline, integrations are probably key to your business. Developer documentation is a no-brainer. Without good documentation, you’d have to rely heavily on sales engineers to hand-hold the customer through the integration process — and that approach simply isn’t scalable.
But if your business is more like Dixa, integrations probably supplement your product rather than being THE product. Perhaps you still build integrations yourself. However, you’ll find it difficult to grow without enabling developers to build integrations independently.
Make it easy to become an integration partner
I once worked at another company that had a lot of integrations. They produced language-checking software similar to Grammarly but for enterprises with large technical writing and marketing teams. They needed to integrate with all sorts of arcane writing tools such as Adobe FrameMaker and Arbortext Editor (don’t worry, I had never heard of these tools either…until I worked as a technical writer). But developer documentation wasn’t a huge priority because an in-house integrations team had always built and maintained the integrations.
Over time, the list of integrations grew, and their expansive integration portfolio became an essential part of their sales pitch: “we can check your content no matter where it lives”. But they simply couldn’t scale without external partners. These partners built and maintained integrations for some of the more exotic content management and authoring solutions. Solutions that the in-house team had no bandwidth to tackle.
The thing was, these partners needed to work independently. The in-house developers had precious little time to hand-hold external developers through the integration process. Very quickly, developer documentation skyrocketed up through the list of priorities. And again, it became a story of a company that had to play catchup. They needed to quickly reduce the strain on their in-house team by improving the quality and quantity of their developer documentation.
You might have guessed why I bolded those words in that last sentence. Remember the classic product management triangle? (”quality”, “quantity”, or “speed”). Yes, it also applies to documentation. So you only get to pick two. And in the case of developer documentation, I think it’s a mistake to choose “speed” and “quantity” — it’s quality or bust. Why? Well, let me first paint a picture in your mind…
You just signed up a new integration partner, and their lead developer has started to integrate your library into their app. She has 10 Stack Overflow tabs open and 5 terminal windows. She’s testing your library in one window while in another window she’s waiting for something else to build….but the stupid thing won’t build because there’s some missing dependency (which she definitely already installed)…and why can’t it find the dumb module…and then she’s also in the middle of a Git rebase which is taking bloody forever because of some annoying merge conflict.
Then, she’s trying to integrate your new library in the middle of all of this. And it’s returning some cryptic 400 error, telling them that a “Socket connected but got destroyed by the parent” even though she copied the command verbatim from the SDK documentation (and what the hell does error that even mean?). Also, what she doesn’t know is that the docs are six months old and still haven’t been updated to match the latest version. And the code that she copied and pasted is woefully out-of-date.
Needless to say, she’s not going to be positively disposed of your product and won’t be in the best mood when contacting you for help.
Sometimes no docs are better than bad docs. Extensive but out-of-date documentation is just going to give developers a false expectation — that they have enough information to get started independently. Your docs might look good at first glance, but when developers start relying on them, they’ll end up frustrated like the developers at the hackathon. Given a choice, I would rather be dependent on a support engineer to talk me through the code than struggle with screeds of awful documentation on my own.
Support your new hires with good documentation
This is a good place to bring up internal developer documentation. Because onboarding a new integration partner isn’t dramatically different from that of a contractor or permanent employee — at least in terms of developer experience.
For a permanent employee, you’re paying extra for all the standard administrative overhead needed to integrate them into your development team. And for contractors, all of that is baked into their higher hourly rates.
The point is the longer it takes to onboard someone, the more it costs your business. As I mentioned earlier, you don’t want to have senior developers answering the same questions over and over again.
If you’re not hiring that often, this problem won’t be so pronounced, so perhaps you can afford to skimp on internal documentation. But if a VC has invested in your business, they’re betting on the fact that you’ll grow fast. That means, in the best scenario, you’ll be hiring new developers every month because you’re doing so well. Once you get some momentum, VCs will get a tad nervous about anything that slows down your growth. We want you to have a streamlined onboarding process that allows most of your team to stay productive.
And what can help with that? Internal documentation, of course! Yes, I know that sounds like an oversimplification. You’re probably thinking, “But writing internal documentation also reduces developer productivity!”. This is true to a certain extent. But anything that increases developer productivity in the long term requires a bit of investment. Your developers probably had to spend a bit of time creating a well-oiled CI/CD system, right? But after that, your developers were probably a lot more productive, and the investment paid for itself many times over. The same goes for documentation.
For example…
I remember when I started in a new team, and my assigned “buddy” was on holiday for the first two weeks of my probation period. He’d thankfully written some extensive documentation about our internal tools, and I was able to mostly keep myself occupied without pestering anyone else with too many questions. Not that it’s bad to ask questions, it’s just silly when you’re answering the same standard questions instead of letting the documentation do it for you.
Now, I’m aware that most of this probably isn’t news to you. If you work for a fast-growing startup, better documentation has probably always been hovering around in your ever-expanding wish list — be it internal or external. Maybe you’ve even hired some technical writers already. If so, great! You’re on the right path. However, if you don’t approach the problem strategically, you run the risk of introducing more inefficiency.
It can be hard to find the ideal technical writer
For example, what if you’ve never hired a technical writer before? Developers know how to interview other developers, but interviewing technical writers?…not so much. While big companies have the luxury of having their senior writers interview new applicants, startups often have to take a stab in the dark. The first technical writer is usually going to report to a developer or a product manager. In other words, people who know very little about what a technical writer does. You’re going to need a writer who can bootstrap a brand new docs process and educate the rest of the team. And if you get the wrong person, you could end up wasting a lot of time.
So what does a good docs process look like? What should you look for in a tech writer? Well, I’ve already kept you reading for a while now, so that topic is best left for another article. I’ll also be covering it in more detail at the Project A online knowledge conference on October 30th. I have a talk called “Write it down! Using documentation to share knowledge and enable developers”, where I’ll be answering these very questions.
Of course, I don’t want to leave you hanging, so here are some resources that I recommend in the meantime:
- Watch: From “Write the docs Prague 2019” Brian Lemke — How to launch your startup with good docs. It’s a great guide for companies that have never hired a tech writer before, and he gives a primer to “Docs as Code”.
- Listen: How to hire API doc writers is a podcast from the prolific tech writing blogger Tom Johnson. He talks to a recruiter about the specific skills that differentiate API doc writers from other types of technical writers.
- Read: A very short summary of what your ideal technical writer should have planned if you hire them: First Technical Writer in a Company — Setting up the Process | Technical Writing Blog.
- Ask us: If you need more specific tips about developer documentation, feel free to get in touch with us at [email protected].