Proposed architecture for new documentation

[Cheetham, Anastasia]

On 2011-02-02, at 11:53 AM, Justin Obara wrote:

> I'm not sure I fully understand the distinction between Components (technical) and Reference (API) though.

Components (technical) would be overviews of each individual component: A technical but more narrative explanation of what it is, how it works; A listing and explanation of the events, functions, options, etc.

The idea for the individual Component pages is for developers to have a starting point for a particular component. Supposed they've seen the marketing-style demo, they like it, and they think "Where do I start?" The component page would serve as the introduction to the technical aspects of that particular component.

The API information would be less narrative, more straight look-up reference: Specifics on arguments and return values, etc.

I'm not yet sure how to deal with the API docs for a component's public functions (as opposed to API docs for Framework functions). How do we maintain the relationship between a component's public functions and the component itself, without burying the API docs within a large overall component page. Any suggestions?

-- 
Anastasia Cheetham     Inclusive Design Research Centre
acheetham at ocad.ca            Inclusive Design Institute
                                        OCAD University