The "Prototype" document model design overview

When we released Sandcastle last July we released it with the “Prototype” document model design. The ‘Prototype” document model was designed with the following ideas:

1. Don’t segregate members by visibility

2. Don’t segregate – Filter

3. Don’t Separate a Type from its Members

4. Better (Chicken Feet) Navigation

5. Tabbed Language Filtering

6. True Language Filtering

7. No Intermediate Overload Pages

8. No Overload Pages At All

The syntax blocks, code examples, and member tables should be filterable by language. Users should pick a single procedural code language in one filter that determines their primary/default view for all of these. Code-behind examples should appear as appropriate for the user's procedural language choice and be clearly labeled and located to indicate their code-behind relationship. The filtering paradigm should translate consistently across online or offline deliverables and the user's filtering choices should persist across pages and sessions.

Because markup languages such as XAML or ASP.NET are not relevant to many reference topics, the language filter should omit them as choices for the user's primary/default view. In the tabbed filtering proposal, a tab for every available language will show as an option. If the user does not select a primary language, the primary/default language that appears should be based on the target audience and product priorities.

Member tables should provide views of members by all members (default view), member category (property, method, etc.), inheritance (inherited, declared), access level (public, protected), and other relevant modifiers (static, abstract, etc.). Member tables should include separate entries for each overload rather than a single entry that points to an intermediate overload grouping page. Member tables should appear on the type pages rather than on separate pages; the Members section should appear after the Syntax section (and its constituent sections). Type tables should appear on the namespace pages and offer views by all types (default view) and by category (class, structure, etc.). These tables should include descriptions for each item and use icons consistent with Visual Studio. Consideration should be given to consolidating filter mechanisms so that users don't have to choose one filter choice from the chrome (inheritance) and other choices directly in the member table (access, modifiers). We believe that using filters for this is more efficient presentation than the current segregation approach used for many of these views.

I will blog more details about the “Prototype” document model soon.