

Ask HN: Github + Posterous for API docs? - matthodan

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!
======
Skywing
Well, Sphinx (<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
I 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?)?

------
aonic
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.S. is fb.com the new rumored FB email service? Any place to sign up for
invites?

~~~
matthodan
Do 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
I 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
Check out <http://readthedocs.org>. It's what you're talking about for Python
docs using Sphinx (<http://sphinx.pocoo.org/>)

