Akamai, a leading network services provider, helps thousands of companies around the world build, deliver, and secure their digital experiences. With a complex set of security, compute, and delivery solutions, creating and maintaining documentation across their product suite was a massive challenge. At Akamai’s scale — with over 9000 employees globally and $3.5 billion in annual review — internal teams were struggling to streamline their documentation and user enablement workflow.
Initially, Akamai was using a customized DITA XML system for product documentation, and a custom Markdown solution for API docs. The division of product documentation and API documentation was often frustrating for customers, who wanted these resources in a centralized place. When product managers and technical writers needed to make updates to the docs, they often struggled with the downtime and fragility of the DITA solution, which needed an extensive amount of engineering support internally.
Seeking a Scalable Solution 🔎
Beth Favini, Akamai’s Senior Director of UX Technical Writing and Learning, spearheaded the transition to a new solution after reaching a breaking point with several publishing outages in one day. While she first considered the possibility of switching to another DITA system, she knew there had to be something else out there — something that would be easier and more efficient for customers and the Akamai team. Knowing they wanted a Markdown-based solution, she found ReadMe and signed up for the free trial.
I spun up a site fairly quickly and thought, ‘this is awesome,’ and reached out to your sales team the same day. Beth Favini, Sr Director of UX Technical Writing and Learning
At first, there was some internal resistance to switching from DITA to Markdown, along with concerns about security. Given how much of the internet Akamai hosts on their network, they have very strict security guidelines and rules. But, over the course of several months, those concerns were addressed, and ReadMe won the team over, one by one.
Publishing Made Faster 🏎
When it comes to their publishing workflow, Akamai has multiple teams with different engineering processes, so it’s important to keep everything as streamlined as possible. They’ve centralized their technical writing function under Beth, with her team being responsible for writing and maintaining all UI, help, and API documentation for the entire company.
The skeptics on my team became fans almost immediately after they started using it. Everyone breathed a sigh of relief, because if we had to fix a typo, we could just fix it ourselves. We didn’t have to wait for a long internal process to happen before the changes were live. Beth Favini, Sr Director of UX Technical Writing and Learning
Especially for their API documentation, the writers are involved from the jump. They collaborate closely with the engineering team and work their magic on each Swagger file to begin writing descriptions of the different API calls and behaviors. The writers work in tandem as releases are still being designed to better understand the problems their customers want to solve — and ensure those solutions are clear in the documentation. Previous software solutions hindered this collaborative process, but ReadMe makes it easier for the teams to stay in sync and create better documentation, as a result.
Developer-Focused Docs 💻
Using ReadMe has given the team more momentum and a greater ability to strategize around API adoption and developer experience. The UX Technical Writing and Learning team works very closely with the Developer Experience and Product Marketing teams to ensure their documentation directly contributes to successful API adoption.
“We’re very developer-focused at Akamai, and the ReadMe platform was one way of demonstrating to our developer customers that we care. Being able to publish API docs from Swagger to our developer hub really connects us to our engineering teams and makes what could be a really dry process very engaging for the user,” shared Beth.
“We do all of the work in Git and then we import or upload the Swagger files to ReadMe, and it publishes beautifully. We get all the nice interactivity, and all of the examples end up in the right place.”
Better Docs Benefit Users and Sales 🙌
Before ReadMe, Akamai struggled to create a coherent experience across the product docs and API docs, given the different backend solutions they were using for each. Being able to put all of their docs in one place was crucial — now, their hub contains all of the configuration and API docs for every product they offer. Using the guides section, they can publish online help and UI documentation side-by-side with API documentation, making it easier for administrators and developers alike to see how Akamai can be used to solve their business and technical problems.
In addition to great feedback from users, the Akamai sales team has reaped the benefits as well. Beth notes, “Our sales folks are very grateful — this makes us much more competitive when we’re showing off our docs. And we know our support team loves that we can respond quickly to any kinds of problems that people find in the docs, and update them accordingly.” From faster collaboration to a better user experience across their product suite, the transition to a ReadMe developer hub has set Akamai up for success.
