[Documentation] defining basic terminology on documentation sect 2.1.2

[SebastianSaliva]

document

This task consists in defining the terminology needed to be able to provide a basic / simple view of the domain/system.

Ideally more than one person should work on this task.

This task may be closed before ALL terminology required is documented, but not before having a basic vocabulary.

Guidelines for terminology:

Terminology - What are the actions that can be performed with these entities? Events? Behaviors? • Profile is not a domain concept, nor is "showing beaches". Emphasize the instantaneousness of the events. "… has just been …". • For the functions it will help to explain the choice of parameter types. For example, "rate : Rating >< Beach >< City >< Activities rating -> Rating". Is this the creating function? In that case Rating does not yet exist and can therefore not be passed in. Is it the update function? OK, in that case the Rating parameter is needed. What about the Beach, City, Activities rating? Is a beach identified by just a name or do we need name and city and activity to rate? Or is it supposed to mean that we can rate beaches, we can rate cities, or we can rate activities? Formalism by itself is not very useful. Formalism should complement natural language explanations. • Some of the terms in the terminology are not from the domain. For example, "account" is not a domain entity. You can widen the terminology to include any term, not just domain terms, and then annotate the terms with the most abstract phase that introduces the term. "Account" would then be annotated with requirements. • A 'domain terminology' would define relevant terms from the domain. Very likely you will also have terms that are not from the domain, but that you also want to define. Also, use the terminology to indicate what kind of phenomenon or concept the term represents. Most of what you write here is better placed in the domain narrative. • Terminology: Seems good for now, try to not include circular definitions. I would change "tourist attractions" for "attractions" for example. You dont make mention of the tourist in its definition either, so it doesnt seem necessary in my opinion. • In the domain terminology you want to clarify terms from the perspective of domain. Some of the terms are actually domain concepts, but you are not relating them to the other domain terms in the terminology. • There is a significant overlap between what is under the "Terminology" and what is under the "entities". There is no reason to have separate sections for domain terminology, domain entities, domain functions, domain events, and domain behaviors. Instead, you can merge all these points together into the terminology and annotate the entries in the terminology with the kind of concepts they are. Again, "user", "web app" would not be part of the domain. You can have a common terminology that includes terms from all phases of development. You can annotate the entries also with the most abstract phase that introduces the term. • There is no reason to have the domain entities, domain functions, domain events, and domain behaviors separate to the domain terminology. I suggest putting all your terms into a single terminology and then to annotate them with the kind of concept or phenomenon they are. While you are at it you might also include terms that are not from the domain, but come about in the development project from other concerns than that of the domain. Of course, then you also want to annotate all the terms with the most abstract phase that introduced them. For example, "patient" is clearly introduced by domain description, whereas "user" is introduced by requirements (several users must be able to use the system simultaneously). • In the domain terminology you want to clarify terms from the domain, but "developer", "navigation bar", … are not from the domain. Terms from the domain could be "beach", "activity", "rating", … If you want to include other terms, not from the domain, you can collect a general terminology and indicate for each term the phase that first introduces the term. For example, "navigation bar" would be tagged to come from implementation/user interface. Some of the terms are actually domain concepts, but the way you define them is not at the domain level. For example, "comment". That a user uploads a comment is an application or interface concern. The domain concept "comment" is e.g. "an annotation (usually as written text) on a beach, an activity, … that helps a reader better understand the specifics and that complements the rating scale". No reference to system, upload, user is made. • Some definitions involve terms that are unrelated to the domain. "Shares: broadcasting a platform content to their connections with other users in the platform, other social media, groups, or individuals." Platform, user, are terms that have to do with the application, but not with the domain. "Sharing" has a meaning purely in the domain, independent of any implementation on any system-to-be. What is that meaning? "User" is not a domain entity: you only have users because you want to make an application. On the domain level you only have cooks, learners, … Look over the domain functions, domain events, domain behaviors and see whether they are really from the domain: i.e. are they purely introduced by the need of describing the domain independently of the application.

[Yahid1]

I checked the information and the documentation is done