Documentation: More real-world Models example

[wphicks]

The example for creating a custom Model (Cat model) might be more helpful if it showcased a more realistic/real-world example of creating a new model. Such an example could help clarify terminology in the Model documentation that might be unfamiliar to a domain specialist (e.g. "collection indexes").

[brianhelba]

Do we want less-fantastical examples (e.g. an Image model instead of a Cat) or more sophisticated examples (e.g. a Litter containing multiple Cat objects, an asynchronous useLitterbox girder_worker task [don't rush her!])?

I can see a case where the fantastical context actually serves to better highlight which concepts are core parts of Girder and associated technologies, and which are placeholders for application-business logic. Whereas if there was an Image model in the example, a new user could more likely get confused as to whether this is something provided naively, or something they're expected to adapt / replace for their own implementation.

Either way, I think it would be positive to have more sophisticated examples which follow Girder's style and best practice conventions, both to illustrate Girder's capabilities and to provide a baseline for people to adapt to their own implementations.

Finally, I think a certain baseline understanding of Girder's technologies needs to be present for developers to be productive. If a new developer is not familiar with MongoDB collections or indexes on a collection, they'd be best served by a directly reviewing a pure MongoDB tutorial, rather than attempting to infer these concepts via their usage by Girder. Of course, if there are certain more advanced topics (and perhaps database indexes are one of them, I'm not taking a position) that need to be reshuffed to be presented later in the learning curve of Girder's introductory documentation, perhaps that could be helpful.

[wphicks]

I generally find documentation that provides a realistic use case provides the best combination of thoroughness and motivation, but I don't have strong opinions here. Maybe walking the user through the example from initial problem to solution would demonstrate clearly enough that there is a custom model being constructed. E.g. "Let's say you want to store and search for image data corresponding to a real-world location. There is no built-in model in Girder that corresponds to such an item. In this case, you could build a custom 'GeoImage' model by...". That may not be the best example, but something like that could be effective.

In terms of explaining terms, perhaps I should rephrase my point slightly. Ideally, a domain specialist looking at our documentation will have a problem that they are trying to solve and see how Girder solves that problem for them. In the particular section that I pointed out, the domain specialist's problem is not "How do I interact with Mongo?" Their problem is "How do I store data about cats in a way that I can easily retrieve and filter that data by fur length?" It's definitely important that we document that this is achieved by creating a collection with a particular set of indexes in Mongo, but running through a real world example will show our domain specialist what that actually means for their particular problem. My point was not to advocate for replicating the Mongo documentation in our own, but to show our domain specialist by example the connection between things they care about (the fur length of cats) and elements of the underlying machinery of Girder (collection indexes).

Part of the reason that I pointed out this section in particular is that one of my former colleagues was interested in using Girder for storing digital artifacts of academic work with a bunch of associated metadata. Though he is perfectly familiar with Mongo, he didn't immediately see the connection between the problem he was trying to solve and our documented features. Since then, I've been keeping my eye out for places where I thought we might do well to provide better motivating examples, and this seemed like a good place to start.