search

robotlegs / robotlegs.github.com

The Robotlegs Website
http://www.robotlegs.org
MIT License
12 stars 5 forks source link

Best Practices Documentation #7

Open joelhooks opened 13 years ago

joelhooks commented 13 years ago

I was looking at alternatives to the wiki format and came across this:

http://readthedocs.org/

BtabOrg commented 12 years ago

I like the idea of being able to automate the updates and ease the task of maintaining the docs with the link you've posted.

What I've found in my experience is that I've always referenced the API documentation a lot more than anything else while working with the project. And in many cases I don't find valid examples of "best practices" or even examples at all.

So could it be possible that in addition to the best possible practices, that code examples are placed in the API documentation, along with access to more descriptive resources?

joelhooks commented 12 years ago

I'd be generally against loading down the API docs with inline examples. Adding LINKS in the API docs would be really helpful. Perhaps links to a maintained index of useful tuts/posts/etc?

On Nov 6, 2011, at 18:48, BtabOrgreply@reply.github.com wrote:

I like the idea of being able to automate the updates and ease the task of maintaining the docs with the link you've posted.

What I've found in my experience is that I've always referenced the API documentation a lot more than anything else while working with the project. And in many cases I don't find valid examples of "best practices" or even examples at all.

So could it be possible that in addition to the best possible practices, that code examples are placed in the API documentation, along with access to more descriptive resources?

Reply to this email directly or view it on GitHub: https://github.com/robotlegs/robotlegs.github.com/issues/7#issuecomment-2648936

BtabOrg commented 12 years ago

Ok, I understand why it's important to not load down the API docs. Links to a maintained index would be ideal. Using pretty URLs to link classes, etc would be a good idea. It could be beneficial to add this to the UX of the new website.