Hacker News new | ask | show | jobs
by lhorie 3930 days ago
> Not every project needs its API documented to be successful.

That's a counter-intuitive claim. Can you give an example?

1 comments

It depends on your definition. API is application programming interface, which means that if your product doesn't intend for it's internals to be called or it is a DSL, etc. you don't necessarily need to have formal API docs- you just need usage docs. If it is a C, C++, Java library, then yes, you probably want API docs/Javadocs.
This is just my opinion, but if you want any other contributors besides yourself, I think you definitely want API docs. Just because it's not exposed to the public doesn't mean nobody cares what a function/class does.

If it has a DSL, or any sort of scripting, as a user you damn well want it to have API docs. It's super frustrating to have a use case the author didn't think about, and you have to figure it out via trial and error because the author didn't think it'd be worth spending a few hours documenting what each thing is supposed to do.

Don't think that just because some projects were successful without API documentation, maybe because they served a particular niche, that means you can just ignore documentation because you feel it's not necessary.

I think you and I have different idea of what API docs are.

I think that good documentation for usage is a great idea, but not all projects need formal API docs, because not all of them intend for the classes in their project to be used as a library.

I agree with you that if your code intends to be used as a library, you should provide API docs.

And, if you expose a service then you should probably provide API service documentation with examples.

I'd add also that usage examples can sometimes go much further than API docs to clarifying things.