Add architecture documentation of controls

Proposal: Add architecture documentation of controls

Summary

Currently there is a lot of documentation on how to use controls, however there is little to no documentation on how a control works, making it harder to fix bugs and contribute to controls. We should add documentation (e.g. a README.md) to controls which explain how the control works internally.

Status of controls

Control	Status
NavigationVIew	Finished
ColorPicker	@robloo is working on this control

Rationale

• Complex controls are huge code bases and not easy to navigate through making it hard to fix bugs
• People who are unfamiliar with a control’s code base can be overwhelmed when trying to contribute, especially with complex controls such as NavigationView or ItemsRepeater

Scope

Capability	Priority
Add documentation on the internal architecture of controls	Must
Explain common “flows” inside a control (e.g. selecting an item inside NavigationView)	Should

Important Notes

A possible documentation “template” could be:

# NavigationView

The NavigationView ...

## Architecture

NavigationView consists of ItemsRepeaters renderin NavigationViewItems.
Every NavigationViewItem notifies the NavigationView whether it got invoked or selected. The NavigationView stores the selection model and informs NavigationViewItems when they got selected.

## Common flows

### Event flows

#### NavigationViewItemInvoked
1. NavigationViewItem gets invoked
2. NavigationView get's informed that an item was invoked
3. NavigationView raises ItemInvoked
4. NavigationView updates selection
5. NavigationView notifies the invoked NavigationViewItem about it's new selection state
6. NavigationView raises SelectionChanged


### UIA flows

#### SelectedItem
...

Ideally we would have this in every control’s folder however for multiple controls, there won’t be much to point out (e.g. SplitButton which essentially only has one flow). In “special cases”, e.g. the CommonStyles project, the README would explain what the “CommonStyles” project is for.

Open Questions/Issues

This would require a lot of “initial” work as this needs to be written first. I would like to help with that if we deem that this is good in the long run.

When a control’s API changes in a lot of cases, these documents need to be updated.

[ranjeshj]

@MikeHillberg @chigy @StephenLPeters as FYI. We currently have the specs repo and the docs site but I think this makes sense in the repo next to the code - would you agree ?

[chingucoding]

All right, I’ll start working on the NavigationView documentation.