3 ms·
One vote for good documentation. Not just a link to the Javadocs; preferably a "getting started" page that covers the most common use cases with plenty of plug
by jordanpg 12y ago
One vote for good documentation.
Not just a link to the Javadocs; preferably a "getting started" page that covers the most common use cases with plenty of plug and play examples (if such a thing is even possible in your case).
Also, getting back to the API reference, I'm grateful when there is a roadmap or overview of the class/package structure so I don't have to crawl through the entire thing.
- kevan 12y ago>Not just a link to the Javadocs; preferably a "getting started" page I wish more java projects had python-style documentation. I can probably figure out how to do things eventually by wading through Javadocs, but they can be really frustrating if all I need to know is how to accomplish the core activity of the project.
- jordanpg 12y agoAmong some, there is a certain "machismo" associated being able to make do with the API reference and nothing else. I think this is a waste of time, personally. I noticed this especially among the Rails developers I've worked with.
- prottmann 12y agoHe talks primarily about a REST-Api not Code-Api. For Code-Api i prefer Javadoc too. For rest-api https://github.com/apidoc/apidoc https://github.com/apidoc/apidoc Within the doc you can add examples for usage and response. But a some common pages with Tutorials / HowTos are nice and should be added to a good documentation. (it depend on the complexity of your project and your audience).