Best Practices Documentation

[joelhooks]

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

http://readthedocs.org/

[BtabOrg]

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]

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:
#7 (comment)

[BtabOrg]

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.