Made by
Made by
Documentation can be a tricky beast to perfect.
Adam Butler, Technical Lead for Nexmo Developer notes,
Adam Butler
“Documenting a product requires a lot of collaboration, has outside influence from engineering and product and often has to navigate around quirks in the product itself. Scale this up to five or six products that you are explaining to customers that have different experience levels and personas, then you’ve got your hands quite full.”
In his talk at DevRelCon London next week, he’ll be speaking about how the Nexmo Developer platform team has been working to meet this challenge, focusing on the open-source platform and tools he built when developing Nexmo Developer. In particular, he’ll be explaining how it has enabled his team build a platform for writing rich documentation collaboratively with ease.
At Nexmo, Adam is instrumental in helping developers to build connected products – and he believes that good documentation is an integral part of developer experience. Not only for providing customers with information, but also for supporting the DevRel team when they are out at conferences and hackathons.
When he initially joined Nexmo, although he’d had a long-running passion for documentation, technical writing had never been a core part of his role;
“I spent the first six weeks researching and defining what I wanted to achieve and identifying the qualities and flaws in what I had inherited. I ended up using my engineering expertise to automate much of our documentation, to provide lots of power and control to anybody who wished to contribute whilst keeping the barrier to entry low. By working on tooling and processes, I’ve been able to start giving the docs back to people with the most domain knowledge and make collaboration easy.”
To make sure that things are articulated concisely and clearly, Adam is emphatic that team effort is key. “We all have different visibility of our products. Engineering can contribute to our API Reference via Open API Spec 3.0 documents. Nobody knows our customers as well as the DevRel and support teams. The Product team understand real-world use-cases the best. And our technical writers should be meticulous about the quality of what ends up being shown to customers. Documentation is everybody’s responsibility.”
There are many things that can go wrong with documentation. Some things, Adam admits, he still sees within the Nexmo platform, though he says, “If I had to pick anything it would be a reluctance to repeat a subject.”
One of the team’s early goals was that the documentation should be accessible in terms of experience, stage of development and customer persona. “Our document types fall into (or in-between) our three stages of documentation: Evaluate, Educate and Accelerate. This means that some content is repeated as we ramp up the complexity and reduce the verbosity to provide appropriate documentation for everybody depending on their stage of development.”
Nexmo’s Developer Platform team is also looking to define and update how they keep up to date with their documentation. “At the moment,” Adam reflects, “we’re still quite reactive and are shipping changes daily from our team’s backlog of known issues, as things are raised against our issue tracker or working on documenting new products. We’ve started to collect documentation feedback and Nexmo have a dedicated support team, I’m really keen to explore processes that we can implement to ensure that we extract the value from these and continually iterate.”
However, augmenting their pure code examples with context has proved quite challenging – especially when making additions serves to break content up. It’s also proved tricky to design a system that can consistently automate across several languages, without making things really difficult for the author.
“Throughout the build of the platform, there has been a constant conflict trying to achieve simplicity alongside having powerful tooling. One example of this is our building blocks that reside on an external repository so they are self-contained, can be tested in isolation and can be cloned by a customer to get started quickly using their favourite platform.”
On the roadmap ahead, Adam’s team will continue to build on their work, iterating as they go. “When comes to documentation, we’re always exploring more useful, exciting and interactive ways to help our customers onboard as easily as possible.”
Come hear Adam’s talk at DevRelCon London 2017 on December 6th.