I've been mulling a new business idea and wanted to get your feedback...<p>The idea: A service for hosting, maintaining, and collaborating on web app documentation. Perhaps a Github meets Posterous for web app documentation.<p>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.<p>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).<p><i>Questions:</i><p>How do you generate/host your API docs?<p>Who maintains your docs?<p>What are the pain points?<p>What features would you want?<p>Would you pay for it?<p>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).<p>Merry christmas!
Well, Sphinx (<a href="http://sphinx.pocoo.org/" rel="nofollow">http://sphinx.pocoo.org/</a>) 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.<p>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.<p>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.
Sounds 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>P.S. is fb.com the new rumored FB email service? Any place to sign up for invites?
Check out <a href="http://readthedocs.org" rel="nofollow">http://readthedocs.org</a>. It's what you're talking about for Python docs using Sphinx (<a href="http://sphinx.pocoo.org/" rel="nofollow">http://sphinx.pocoo.org/</a>)