Restructure docs & website for usage of an API.md document #1384
Description
@nmccready Coming over from #1327 re your comment about an API.md document.
I think a non-website approach to API documentation would be great. I'd certainly help.
D3.js uses its wiki section in a similar way, but I like the "single, giant, mostly plain-text document" approach of an API.md a little better. Loads fast, nicely formatted, internally linkable, and robustly Ctrl+F'able. Doesn't force you to laboriously visit a bunch of different pages (or more time-consuming & otherwise costly, having the project implement or adopt---and then maintain---a custom search mechanism on the project website).
Also, an API.md would probably have tighter "control" than a wiki, unless the wiki option to restrict editing to collaborators is enabled. The latter isn't an awful thing, but it'd be nice to keep a place for non-collaborators to contribute doc-like things easily w/o a PR (as long as it wasn't abused).
Having the website act primarily as a showcase for both impressive/multiple-component and illustrative/single-component examples (separately? highlight a few of the former, provide a lot of the latter) seems like an awesome organizational simplification to me. Could include long-form detailed walk-throughs of one or two (or more, eventually) larger choice examples. Top it off with a general summary/intro, and then pointers to the meat & potatoes here on the repo pages. Maybe leave out the activity streams and collaborator list? Keeping it as clean and easy to maintain as possible. (Not to harp too much on D3, but its website has this spirit.)
The contents of API.md could also include links to applicable examples at the website.
All major/minor releases could have their own API.md. Or, only all major releases have their own, and minor release differences are annotated, e.g. "betterFoo() --- New in 3.2".
More ideas & discussion welcome. Non-idempotent implementation of increaseHoursInADay() also welcome to help tackle this, har har.