Documentation, one of the great neglected areas of software development, is finally getting some attention, with a number of relatively new tools such as @Asciidoctor, and Cyrille Martraire’s DDD inspired book on "living documentation.” For an API documentation can be considered essential. Gregory Koberger is working on a system with the intent of connecting developer documentation more directly to APIs and the API dashboard.
InfoQ recently interviewed Gregory in his role as CEO of Readme.io, the company he created to realize his vision of API documentation.
InfoQ: Can you describe the story behind Readme.io’s creation and how it has evolved?
Gregory Koberger: Sure, my background is that I'm a programmer and designer interested in developer tools because there is a unique set of design challenges with them.
Having spent a lot of my time writing and reading documentation, I thought there should be a better way to do it. About five years ago, I decided this was what I wanted to work on, but I had a hard time getting started. Thankfully companies like Stripe and Twilio have shown people how important documentation is. About 1 year ago we launched.
It's been going amazingly well. We definitely found a product and problem fit where a lot of people need better documentation. We are getting to the point where we want people to start changing the way they think about documentation. It shouldn't be static. It should change depending on who is looking at it and how knowledgeable they are.
InfoQ: What is your vision behind Readme.io?
GK: APIs consist of three parts: the documentation, the dashboard (to generate developer keys and so on) and the API itself.
I want to start bringing them together. The API knows about the code and the data. The dashboard knows about the user. Documentation traditionally has been static and knows about none of them.
For example, imagine if the documentation knew the user language and could display a code snippet directly for them or imagine if the documentation knew that the user got a specific error and could help him solve it.
InfoQ: What are the main challenges API teams face when they need to document their APIs?
GK: One big problem is that it's not a priority. People, including myself, are very bad at documenting an API when we write it. It’s very hard to step back and know what someone new to using your API would need to know. People also struggle keeping the documentation up to date.
InfoQ: How does Readme.io help? What are its main features?
GK: Right now, we focus on documentation. We are like WordPress for code and APIs. We make it really easy for you to provide a developer experience for your customers.
Readme has support forms, landing pages, a place for tutorials and more. We let people play with the API right on the web page, make changes and allow them to see what happens. We can also auto-synchronize API documentation from GitHub and display it nicely.
InfoQ: How does Readme.io compare to open source alternatives such as Swagger UI or Slate?
GK: One of the nicest things about Readme.io is that everyone in the company can contribute, not just the developer. We will soon support Swagger so we can easily replace Swagger UI. We also believe that the community should be involved in the documentation process. So we have something called suggested edits where anyone inside or outside the company can suggest changes using a nice drag and drop editor.
InfoQ: Can the documentation created with Readme.io be deployed on an existing developer portal?
GK: The goal of Readme.io is to be a developer hub. Currently, you can use it with an existing hub. In the future we want to bring documentation, the dashboard and support together. When they are all in the same place, they work really well together.
InfoQ: Do you support API definition languages such as Swagger, RAML and API Blueprint?
GK: Yes. Currently we use something called APIdoc. We are going to release support for Swagger, RAML and API Blueprint soon.
By documenting your API semantically, you create more value compared to writing paragraphs of text because you can start generating SDKs or code samples tailored to the user.
Right now, we are limited to importing those languages. We think it is important to let people export them as well. Readme.io is lucky to be at the center of their developer experience and we really want to use that opportunity to be a hub for many different API companies.
InfoQ: How do you support various API development workflows such as Code-first and API-first?
GK: Very often APIs are written in a way that just replicates the way the main web site is built. That can be bad because many times you use the API to do things that the web site cannot do.
So, I think it's important to think about the API as a separate entity from the web site because you want it to be flexible enough to do things that your web site cannot.
InfoQ: What is the best way to describe an API and keep it in sync with the evolution of its implementation?
GK: There are a lot of ways to describe APIs like Swagger, RAML, and API Blueprint. We picked APIdoc because the documentation was very close to the code itself. It's similar to Javadoc where the document is a comment close to the code as opposed to being in a separate file. We can sync that from GitHub automatically.
InfoQ: In a typical API team, who should be responsible for documenting the API?
GK: Everyone! Traditionally, only developers do the documentation. However, APIs are very important to business, marketing and product management groups as well. We want to make it so that everyone from the developers to the CEO can update the parts of the documentation that are relevant to them.
We think the community is incredibly important as they have questions and use cases that other people wouldn't have.
InfoQ: From your point of view, should API documentation and operational API management be treated separately?
GK: One thing that I really like about the API ecosystem now is that there are many companies doing specific things very well. With larger API management companies, they try to do everything and do most things poorly.
I think that API management and documentation should be separate. However, they should be tightly integrated.
InfoQ: What are the upcoming features and the timing for the next version of Readme.io?
GK: We are working on a big redesign right now that should be out in approximately a month. Aside from looking nicer, there is going to be a separate section for reference guides and another for examples.
For people writing documentation, it will be more obvious where everything goes and what should be included in documentation. For the end-user, it will be more obvious to know where to go to get the information that they want.
Things like Swagger import are very important since we want to start automating much more of the process of documenting your API.
Documentation is something most developers spend their time either reading or writing. It is the interface we use to interact with the code library or the API and I'm really excited about the ways that Readme is going to be able to change the way people do that.
You can try Readme.io for free, and it remains free for open source projects. For proprietary software the company offers a basic package, comprising 3 documentation versions and 1 admin user on a Readme.io subdomain is $14/month. The developer hub version which allows you to use your own domain, and supports 10 admin users, is $59/month.