[API] Begin adding notes for API redesign

docs/src/design/index.md

@@ -0,0 +1,3 @@
+Design proposals:
+
+* [API Redesign](proposals/APIRedesign.md)

docs/src/design/proposals/APIRedesign.md

@@ -0,0 +1,233 @@
+# Overview
+
+The purpose of this document is to review feedback on Open MCT Web's
+current API and propose improvements to the API, particularly for a
+1.0.0 release.
+
+Strategically, this is handled by:
+
+* Identifying broader goals.
+* Documenting feedback and related background information.
+* Reviewing feedback to identify trends and useful features.
+  * In particular, pull out "pain points" to attempt to address,
+    as well as positive attributes to attempt to preserve.
+* Proposing a set of API changes to address these "pain points."
+  * This also takes into account scheduling concerns.
+* Once agreed-upon, formalize this set of changes (e.g. as UML
+  diagrams) and plan to implement them.
+
+# Goals
+
+## Characteristics of a good API
+
+A good API:
+
+* Is easy to understand.
+* Rewards doing things "the right way."
+* Saves development effort.
+* Is powerful enough to support a broad range of applications.
+
+These characteristics can sometimes be at odds with each other, or
+with other concerns. These should typically be viewed as participants
+in trades.
+
+## Evaluating APIs
+
+APIs may be evaluated based on:
+
+* Number of interfaces.
+  * How many application-specific interfaces do I need to know to
+    solve a certain class of problems?
+* Size of interfaces.
+  * How many methods does each interface have?
+* Depth of interfaces.
+  * Specifically, how many methods do I need to call before the return
+    value is of a form that is not specific to the API?
+* Clarity of interfaces.
+  * How much documentation or learning is required before an interface is
+    useful?
+* Consistency of interfaces.
+  * How similar is one interface to an analogous interface?
+* Utility of interfaces.
+  * How much development effort is reduced by utilizing these interfaces,
+    versus accomplishing the same goals with other tools?
+* Power of interfaces.
+  * How much application functionality can I influence with the interfaces
+    that are available to me?
+
+In general, prefer to have a small number of simple, shallow, clear,
+useful, powerful interfaces.
+
+# Developer Feedback
+
+## Developer Intern Feedback
+
+This feedback comes from interns who worked closely with
+Open MCT Web as their primary task over the Summer of 2015.
+
+* Initially, it was confusing that many things in files that are in
+  very different locations in the code base refer to each other.
+  * Perhaps explain more the organization strategy behind the
+    different main sections, like "commonUI" vs "core".
+* This may be just me, but there are often long chains of related
+  functions calling each other, and when I had to modify the behavior,
+  I had a hard time remembering to look for the highest level function
+  in the call chain to change. I also sometimes had a hard time finding
+  the connections between the functions. But, that is important because
+  the implementation of the functions along the chain may change later.
+* One very helpful thing that you could add might just be documentation
+  that is not in paragraph format like in the current developer guide.
+  I would just like a list of all the functions and members of each kind
+  of object there is, and descriptions of what they are and how they're
+  used.
+  * Also, the current developer guide pdf's words that are in 'code font',
+   rather than the normal text, are not searchable.
+   (Depending on the pdf viewer.)
+* I do appreciate that there is some example code.
+* I am still slightly confused about what "domainObject" refers to in
+  different situations.
+* The tutorials are helpful, but only really for designing new views.
+  It doesn't help much with gaining understanding of how the other parts
+  of the application work.
+* The general idea of 'telemetry' in this context is kind of confusing.
+  It is hard to figure out what the difference between the various ways of
+  dealing with telemetry are. e.g., what is the difference between just
+  "Telemetry" and the "Telemetry Service"? There are many
+  "Telemetry Thing"s which seem related, but in an unclear way.
+
+## Plugin Developer Feedback
+
+This feedback comes from developers who have worked on plugins for
+Open MCT Web, but have not worked on the platform.
+
+* Not a lot of time to work on this, made it hard to get up the learning
+  curve.
+  * Note that this is the norm, particularly for GDS development.
+
+## Misc. Feedback (mostly verbal)
+
+* Easy to add things.
+* Separation of concerns is unclear (particularly: "where's the MVC?")
+* Telemetry API is confusing. In particular, `TelemetrySeries` should
+  just be an array.
+  * Came out of design discussions for Limits.
+* Capabilities are confusing.
+
+## Victor's Notes
+
+* Bundle mechanism allows for grouping related components across concerns,
+  and adding and removing these easily. (e.g. model and view components of
+  Edit mode are all grouped together in the Edit bundle.)
+
+## AngularJS
+
+Angular 2.0.0 is coming (maybe by end of 2015.)
+
+It will not be backwards-compatible with Angular 1.x.
+The differences are significant enough that switching to
+Angular 2 will require only slightly less effort than switching
+to an entirely different framework.
+
+We can expect AngularJS 1.x to reach end-of-life reasonably soon thereafter.
+
+Our API is currently a superset of Angular's API, so this directly effects
+our API. Specifically, API changes should be oriented towards removing
+or reducing the Angular dependency.
+
+### Angular's Role
+
+Angular is Open MCT Web's:
+
+* Dependency injection framework.
+* Template rendering.
+* DOM interactions.
+* Services library.
+* Form validator.
+* Routing.
+
+This is the problem with frameworks: They become a single point of
+failure for unrelated concerns.
+
+### Rationale for Adopting Angular
+
+The rationale for adopting AngularJS as a framework is
+documented in https://trunk.arc.nasa.gov/jira/browse/WTD-208.
+Summary of the expected benefits:
+
+* Establishes design patterns that are well-documented and
+  understood in industry. This can be beneficial in training
+  new staff, and lowers the documentation burden on the local
+  development team. If MCT-Web were to stay with its current
+  architecture, significant developer-oriented documentation
+  and training materials would need to be produced.
+* The maintainability of MCT-Web would be enhanced by using a
+  framework like Angular. The local team would enjoy the benefits of
+  maintenance performed by the sponsor, but would not incur any cost
+  for this. This would include future upgrades, testing, and bug fixes.
+* Replaces DOM-manipulation with a declarative data-binding syntax
+  which automatically updates views when the model data changes. This
+  pattern has the potential to save the development team from
+  time-consuming and difficult-to-debug DOM manipulation.
+* Provides data binding to backend models.
+* Provides patterns for form validation.
+* Establishes documented patterns for add-on modules and services.
+* Supports unit tests and system tests (tests which simulate user
+  interactions in the browser)
+* Angular software releases can be expected to be tested, which would
+  allow MCT-Web developers to focus on MCT-specific features, instead
+  of the maintenance of custom infrastructure.
+
+## Actual Experience with Angular
+
+Most of the expected benefits of Angular have been invalidated
+by experience:
+
+* Feedback from new developers is that Angular was a hindrance to
+  training, not a benefit. ("One more thing to learn.") Significant
+  documentation remains necessary for Open MCT Web.
+* Expected enhancements to maintainability will be effectively
+  invalidated by an expected Angular end-of-life.
+* Data binding and automatic view updates do save development effort,
+  but also carry a performance penalty. This can be solved, but requires
+  resorting to exactly the sort of DOM manipulations we want to avoid.
+  In some cases this can require more total development (writing a
+  poorly-performing Angular version, then "optimizing" by rewriting a
+  non-Angular version.)
+* Expected reduction of test scope will also be invalidated by an
+  expected end-of-life.
+
+Other problems:
+
+* Hinders integrating non-Angular components. (Need to wrap with
+  Angular API, e.g. as directives, which may be non-trivial.)
+* Interferes with debugging by swallowing or obscuring exceptions.
+
+# Feedback Review
+
+## Problem Summary
+
+The following attributes of the current API are undesirable:
+
+[ ] It is difficult to tell "where things are" in the code base.
+[ ] It is difficult to see how objects are passed around at run-time.
+[ ] Multiple interfaces for related concepts (e.g. telemetry) is confusing.
+[ ] API documentation is missing or not well-formatted for use.
+[ ] High-level separation of concerns is not made clear.
+[ ] Interface depth of telemetry API is excessive (esp. `TelemetrySeries`)
+[ ] Capabilities as a concept lack clarity.
+[ ] Too many interfaces and concepts to learn.
+
+## Positive Features
+
+It is desirable to retain the following features in an API redesign:
+
+[ ] Creating new features and implementing them additively is well-supported.
+[ ] Easy to add/remove features which involve multiple concerns.
+
+## Requirements
+
+The following are considered "must-haves" of any complete API
+redesign:
+
+[ ] Don't require usage of Angular API.
+[ ] Don't require support for Angular API.