☰ Menu
☰ Menu
eBay has earned a reputation among both buyers and sellers on its platform as being easy to use. Recently, based on feedback from partner organizations that sell large volumes of products through the eBay site, it saw a need to improve the documentation it provides for the APIs that these companies use to seamlessly connect their companies’ e-commerce applications with the eBay platform.
On its developer portal, eBay provides an extensive library of API documentation for these specialized users. The library has grown significantly over the last two decades, even to the point that current users were finding it difficult to locate the specific information they needed. In looking at how to make the developer portal more user-friendly, eBay realized that its process for authoring and publishing this information had become extremely complex, leading to delays. Those delays in turn were slowing down eBay’s release of new software, further frustrating users. A related challenge was that eBay’s internal API development team lacked the bandwidth to support documentation development.
After looking at multiple alternatives — including hiring more staff or using a staffing company to provide technical writers — eBay approached Contiem. Contiem proposed that it provide a project team of technical writers with the requisite API experience, and led by a Contiem project manager. The team would focus on both developing the required documentation and identifying opportunities for process improvements, leveraging its experience doing similar types of work at companies such as Google, Cisco Systems, and TransUnion. The writers would work closely with the eBay developers while the project manager would ensure the team was focused on the priorities set by eBay management. With the Contiem approach, eBay saw the opportunity to spend less time focused on software documentation and more time on software development and decided to engage Contiem.
Contiem went to work assessing the current state of eBay’s API documentation processes. With extensive experience in supportive software documentation, we relied on our deep familiarity with such tools as JSON, MadCap Flare, OAS/Swagger, XML, and GitHub. Just as importantly, we assigned a dedicated project manager to “virtually embed” with eBay’s stakeholders in order to ensure that new documentation was being created and delivered to match the cadence of the organization’s software releases.
As part of the writing process, our team tests various APIs to ensure the quality and accuracy of the documentation, minimizing the amount of time eBay’s developers spend assisting in the documentation process. Six weeks into the engagement, the Contiem team had implemented a new scrum/sprint-based process, and was successfully delivering on-time API documentation utilizing eBay systems.
By the third month of our engagement, eBay requested that Contiem formally analyze the documentation portal authoring process, and provide recommendations for improving the portal itself. Contiem conducted interviews with key stakeholders across multiple teams, and dove into the portal’s underlying code. This effort resulted in a comprehensive improvement plan, including a redesign of the portal, a reorganization of the content navigation, and a streamlined documentation publishing process. To maximize our impact, we structured and presented our plan to eBay as a phased approach to take place over eight months.
After receiving our recommendations for improvement, eBay agreed to the overall plan. They also requested that we expand the project team to accelerate the improvements. The revamped eBay Developer Portal went live in March 2022.
Contiem has handled hundreds of eBay documentation requests, including many large updates and all new API releases. This includes many high-visibility initiatives, such as eBay’s Managed Payments initiative, which effected a fundamental transformation of buying and selling on the platform. We have helped reduce documentation development time by 20%, and vastly improved the portal’s user experience to help onboard and retain new customers.
eBay has been highly satisfied with the API documentation support Contiem has provided over the years of our engagement. API documentation has caught up to the schedule of the software releases, and the quality of the documentation has resulted in fewer accuracy issues, reducing the burden on eBay Customer Support. Based on how well the engagement is going, eBay has determined not to pursue plans to hire additional internal documentation staff and continue to outsource the process instead. In addition, eBay is considering expanding the engagement to include broader support for other groups within eBay.