Posted on 10-24-2012
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.
comments powered by Disqus
Winning in the API Economy
|Download as PDF|
Latest Blog Posts
- Thank You For Your API Evangelist Blog(s)
- Video From The Hypermedia Panel At API-Craft In Detroit Last Month
- Please Open Source Your API Before Shutting It Down
- Explaining My Work Around APIs In Higher Education To Institutions
- You Can Have An API Just By Choosing Products And Services That Have APIs
- Using Excel As An API Datasource And An API Client For The Masses
- Brewing Up Something Awesome With The Jive Software API
- Relationship Between APIs And Containers
- Real-time and Visualizations Will Be Key in Financial API Deployments
- Notification Focused Startups Within Leading API Ecosystems
- APIs That Do One Thing And Do It Well Like ZipLocate
- Which API Do I Need?
- The Expanding API Conference Landscape
- Ocotoparts Open Source Google Spreadsheet
- Andrew Nacin Of WordPress @APIStrat Chicago
- Push Button API Deployment With The Heroku Button
- WordPress Style API Modules For Government
- The Heroku HTTP API Design Guide
- What I Have Been Calling API Trends, Are Slowly Being Baked Into API Operations
- FDA Finding Their API Mojo With A New Drug Label API
- Adding PokitDok To Healthcare Research And The API Stack (Well They Did)
- Why I Am Continuing To Integrate Zapier In My Business Workflow
- Who Is Going To Build The Uber API Platform For The Sharing Economy?
- The API Focused Dev Shop
- Route SMS Messages To Google Spreadsheets Via Twilio API With TwilioSheet