Out of date API documentation is by far the most common mistake API providers make, and also the number one pain point for API developers. It makes sense that you will want to keep your API documentation in sync with each version of your API, and one way to handle this is to version them both, using Github.
To use Github for your API documentation, all you need to do is create an single public repository, which you can use to manage HTML versions of your API docs. By putting your API documentation in its own repository you can keep the version of the API code repository in sync with it's corresponding documentation.
With the API documentation in Github, you can then easily publish to your API area or just allow developers to go directly to the Github repository and browse documentation there.
To help you edit your API documentation, you can use tools like prose.io, which will allow even non-developers to assist in maintaining API documentation, with all changes stored neatly in a central Github repository.
Storing API docs in Github will also make them more portable. Some developers may wish to download a copy for offline work, or just prefer having locally for their own reference.
With the right approach to managing your API docs with Github, you can easily keep them up to date, in sync with your API, while also making them easily accessible by all API consumers--without much of the headache often associated with managing API documentation.
|Documentation, GitHub, Github 101|
blog comments powered by Disqus
Latest Blog Posts
- Dropbox As Your Apps Default File System
- DataSift's Open Source World
- Salesforce Adds Sandbox Templates
- An Open Source Code Catalog for your API
- Multi-Tenancy with WSO2 API Manager
- Ember, Angular, Backbone, Single Page Applications and APIs
- APIs in DFW
- Adding API Broker Under Monitoring for API Aggregators
- The Dark Matter That Make APIs Work
- Potential for API Aggregators to Provide Valuable Industry Data
- My Talk Tomorrow Night at the Dallas-Forth Worth API Professionals Meetup
- The White House Releases An Open Data Strategy
- When API Success Signals Begin Working Against You
- Get To Know Which Languages Your API Developers Are Using
- Twitters Developer Area is More Embeddable Than API
- Overview Of Backend as a Service (BaaS) White Paper
- Make Sure And Have Multiple KPIs For Your APIs
- API Enabled Toys For Our Children
- I Am Speaking At The Dallas-Forth Worth API Professionals Meetup May 14th
- How Much Do You Spend Attracting and Supporting Freemium API Developers?
- What Does The API Evangelist Do?
- Startups Need To Work Together on API Definitions
- Parse Is Successful By Truly Solving Problems for Mobile Developers
- API Commandment: Thou Shalt Not Forego Talking to a Person
- API Trends