HackerStreet.IndiaNew | RSS | Comments | Ask HSI | Leaders | submitlogin
Ask HSI: Suggestion on choosing a documentation tool
8 points by avlesh 416 days ago | 11 comments
People, we (at WebEngage) need some suggestions on selecting a documentation tool. This is for rolling out the documentation of our public API. We can use anything - hosted, SaaS, open source etc as long as the tool serves some of these purposes -

1. We need easy indexes to list topics covered in the API documentation.

2. We need to be able to build a rich documentation (nice HTML/CSS) with a whole lot of code samples.

3. The document should support easy versioning - as in it should be easy for us and end users to figure out that the documentation is for, say, Version 1.3 of the API.

4. Should have cool looking tables (can be wiki engine based) to explain methods, arguments and outcomes. We really love Google Maps API for it - https://developers.google.com/maps/documentation/javascript/3.7/reference

I'll possibly get to learn more on what to expect from such a tool based on your responses. Look forward to some cues.



6 points by jagira 416 days ago | link

Github's dev site is one of the best. http://developer.github.com/v3/

Its source is open as well. https://github.com/github/developer.github.com

The licensing terms are not clear, though.

-----

1 point by avlesh 415 days ago | link

Oh, this is sweet. Keeping this on the top of my list. Thanks Jigar.

-----

4 points by djinn 416 days ago | link

I prefer sphinx with its simple RestructeredText document approach. http://sphinx.pocoo.org/

-----

2 points by nischal 416 days ago | link

Haven't used this yet but been thinking of using this for GrabInbox - https://github.com/mashery/iodocs

-----

2 points by hrasm 416 days ago | link

doxygen

-----

2 points by sushrutbidwai 416 days ago | link

There are few tools [1] which provide entire API management (authentication, blocking, throttling, licensing and documentation). Since you need only for documentation, it could be not a good fit, but do have look at them.

Otherwise a simple wiki with required plugins for code samples should suffice. Another way is to use Javadoc[2] for documenting API at code level and use CI tools to publish them to HTML/CSS. CSS you can write your own. This will not only make documentation available as you change things, but will be maintained at code level and hence perhaps better quality.

[1] - http://blog.programmableweb.com/2011/10/19/api-service-provi...

[2] - Assuming web services are written in Java.

-----

1 point by avlesh 415 days ago | link

A complete management tool seems to be a bit of an overdo right now. I'll look at it anyways. In my experience Javadoc's on the web doesn't work great mostly for the kind of content you want to display on your API documentation - code samples, rich HTML displays etc. It becomes too much of a pain to add all of that to your source code.

Thanks for the pointers Sushrut.

-----

1 point by avlesh 384 days ago | link

Update: We chose Sphinx.

-----

0 points by rakeshpai 416 days ago | link

I can't believe you haven't solved this problem yet. Give me a call, and we'll talk about this. Or you can do google searches.

-----

1 point by avlesh 415 days ago | link

Boy, you got downvoted (FYI, its not me)! And based on my HSI experience, trust me, there's more to come :)

Anyways, it was about hearing it from everyone else on their tool of choice. Would have been nice if you mentioned yours.

-----

2 points by rakeshpai 413 days ago | link

This is weird. I haven't logged on to HSI in months, and my activity on the site reflects this. Even more weirdly, I don't actually know about API documentation tools. Wonder how this happened. Password has been reset.

-----




HSI Updates & Announcements