Topic on Talk:Wikimedia Engineering Architecture Principles

@DKinzler (WMF) What is an "abstract domain model"? Would it be possible to use less jargony language here?

I came here to say something similar; in general, one useful addition to many of these principles would be specific examples where SHOULD/MUST have been followed correctly and places where we could improve.

I think I understand what is meant by "APIs geared towards a specific user interface MUST be considered part of the component that implements that user interface, and MAY be considered private to that component" but I'm not sure what specific instances/examples (if any) this statement was written in response to.

> What is an "abstract domain model"?

For example, "title", "page", and "revision" are entities in mediawiki's abstract domain model. APIs should be built around such concepts. In contrast, and API that exposes internals, like the database schema, should be avoided. APIs that cater to a specific client are OK (e.g. CategoryTree has an API foe returning rendered sub-trees), but should not be used by anything else (they are "private to that component").

I'm not sure how to rephrase these points to make them clearer. We can add examples, I just fear that it will clutter the page too much. Suggestions?

So should that say "SHOULD be considered private to that component" instead?

> I'm not sure how to rephrase these points to make them clearer.

Link to Wikipedia articles on the first use of each "term of art" in the doc? If you are using terms of art that are so obscure to not be covered at least as a sub-topic on an enwiki article then that might be a good guide on rewording. Unless of course the term of art is purely of local origin; in that case I would hope there is a mw.o or wikitech page you could link to for clarification.

Ok, I'll add links.

For the case at hand, see domain model.