[API] Review API about openmct

[slhale]

Some notes from my experience so far:

• 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.

This is just stuff off of the top of my head, and also I have no idea if these apply to everyone.

[slhale]

I found another instance where the developer guide can be confusing.

For action contexts, all that the guide says about them is that "An action context is a JavaScript object with the following properties:

• domainObject: The domain object being acted upon.
• selectedObject: Optional; the selection at the time of action (e.g. the dragged object
  in a drag­and­drop operation.)"

But, I have found instances which refer to action contexts having other properties. The implementation of getActions takes an action context, and uses context.category and context.key.

[shivamndave]

Here are just a couple pain points:

• No guide for the UI and front end for the HTML/CSS part of Open MCT Web. Not sure if this is applicable or needed for developers, however would be helpful to any front end development
• Found it difficult to follow the plot controller & subplot functions/features, such as zooming.
• If the developer guide could have for references to which files or functions are key for gestures, browse navigation, etc it would be helpful for future developers as a place to start looking. I found it occasionally difficult to find which files or functions I wanted at first.

[VWoeltjen]

Marking resolved - considering this feedback now in the context of #69

[VWoeltjen]

Reopening to solicit additional feedback from @akhenry; would like to get some first impressions

See also #69

[akhenry]

Some random thoughts

• The path that data takes from telemetry source to visualisation is a little arcane. I've implemented a new telemetry source now (the public MSL REMS data) and I'm still not confident I completely understand how a plot gets telemetry from providers.
• The dependency management approach makes it difficult to follow a dependency to its source. A component declares a dependency by name, but figuring out what that is at runtime can be tricky. After a while you get a feel for where things live, but initially it involved searching all of the bundle.json's to find where that dependency is defined. This is a problem more broadly with dependency injection, and this approach does have its strengths, but it can make following the code difficult.
• Generally speaking, there is quite a lot of indirection and abstraction in the framework. Again, it makes for a really powerful and extensible platform, but it does make the learning curve pretty steep.

[akhenry]

Representations and views are confusing for a new developer. Can we combine these or do away with them entirely?

[VWoeltjen]

Completed in context of #263