3 ms·
Ask HN: Github + Posterous for API docs?
I've been mulling a new business idea and wanted to get your feedback...
The idea: A service for hosting, maintaining, and collaborating on web app documentation. Perhaps a Github meets Posterous for web app documentation.
Nearly every web API has some form of documentation. However, there doesn't appear to be a 'best practice' for generating, hosting, and maintaining such documentation.
I think the hosting of API documentation should be offloaded to a third-party service, like we've seen with blogging (Posterous) and source code (Github).
Questions:
How do you generate/host your API docs?
Who maintains your docs?
What are the pain points?
What features would you want?
Would you pay for it?
Thanks in advance for your feedback. I'd like to build a prototype if people like the idea-- shoot me an email if you want to help (matt.hodan at fb.com).
Merry christmas!
- Skywing 16y agoWell, Sphinx (http://sphinx.pocoo.org/ http://sphinx.pocoo.org/) generates really good Python documentation. Perhaps if you were able to come up with something that also generated nice documentation, but was language agnostic, that might be cool. I'm also a fan of the recently popular annotated source code style of documentation. Although I feel like this style of documentation takes more effort to use. If your service just hosted API docs, perhaps you could just make a platform that allows people to choose their API documentation platform, such as Sphinx, and somehow make it easier to generate it and deploy it on your servers. This might be enough of a reason for people to use your service. I wouldn't pay for it, though, unless you had some compelling reasons why I should. GitHub makes their basic project hosting free and it provides much more functionality and utility than a API documentation service might.
- matthodan 16y agoI hear you on Sphinx-- definitely looks like a great tool, though I haven't used it before. Do you know if Rails has something similar? Also, would you use sphinx to generate end-user docs (like the kind you find publicly available on Heroku, Twilio, SimpleGeo, PayPal, Hoptoad, etc.) or just internal docs? What level of control do you have over visibility of docs (i.e. can certain docs be private and others public?)?
- matthodan 16y agoHow about a service that took annotated source docs at commit and automatically updated a hosted public-facing documentation reference?
- aonic 16y agoSounds like a good idea. For the UI, I think you should allow double-click editing of specific paragraphs and sections, and the changes should be kept a list (git status) that the user could request to be pulled by the maintainer. P.S. is fb.com the new rumored FB email service? Any place to sign up for invites?
- matthodan 16y agoYup. You can sign up here: http://www.facebook.com/about/messages/ http://www.facebook.com/about/messages/
- matthodan 16y agoDo you think people would be interested in a full git workflow (i.e. you maintain the docs via a git branch that you push to the service)?
- aonic 16y agoI think that workflow might work if people (maintainers) are submitting HTML or README.md's or whatever for their docs. But for 'collaboration' with visitors/readers, it would need t be simple. I personally wouldn't want to pull out the command line and git clone, edit, commit, push just to get some tweaks or examples added to the docs unless it was a project I contributed to regularly. Another thing that might come in handy is something like code review tools that let you add comments for specific line numbers -- but for sections/paragraphs of the documentation. This could also serve as a revision history discussion as well as questions/comments on the information
- tdavis 16y agoCheck out http://readthedocs.org http://readthedocs.org. It's what you're talking about for Python docs using Sphinx (http://sphinx.pocoo.org/ http://sphinx.pocoo.org/)