DrLeturc commented 2 years ago

We need a template to create and let the community propose new motivating scenarios.

I propose to include in the folder scenario a template for building scenarios : https://github.com/HyperAgents/ns.hyperagents.org/blob/master/scenarios/TEMPLATE-SCENARIO.md

This file could be used by the community when they want to create a new motivating scenario https://github.com/HyperAgents/ns.hyperagents.org/issues/74.

A motivating scenario in SAMOD is currently composed by :

An unique identifier (the ID of the issue?)
A story (name)
A short description of the covered feature by the motivating scenario
A set of examples (the story+references to Agent/Workspace/Artifact and all resources involved?)
A glossary of new terms (what are the needed new resources ?)
Competency questions = (identifier, question, outcome, exemplar_answers, depends_on);
Formal description = (SPARQL request)

Do you see interesting characteristics that a motivating scenario should consider ?

maximelefrancois86 commented 2 years ago

We may use github issue templates for this: https://docs.github.com/en/communities/using-templates-to-encourage-useful-issues-and-pull-requests

FabienGandon commented 2 years ago

quick reaction:

as a scenario may address several issues you may want to differentiate the issue of the scenario itself from the issues covered by the scenario.
👍 to use existing templating mechanism: anything that integrates git practices to ontology practices is to be explored
avoid situations where you have to handle symmetric link / backward links manually: e.g. for the glossary of terms either we introduce an issue for each term pointing to the scenario or we point to each issue from the scenario but having to maintain coherence of the same list twice is not good ; we must avoid redundancy and coherence maintenance tasks
the "scenario" issues should correspond to events of the life-cycle of a scenario rather than to the scenario itself basically: create, update, delete/drop.

FabienGandon commented 2 years ago

I made a test on having "query-based links" to maintain links between issues and scenarios see test #79

DrLeturc commented 2 years ago

Title of your new motivating scenario

Short introduction to present the context and the problem that the motivating scenario is going to solve

A short description

Give a short description of the covered features as a little story ?

Covered features

The list of covered features :

Complete the list of covered features

A set of examples

The list of examples show concrete use cases

The name of the use case

Your informal use case

A glossary of new terms

List of new terms introduced by the motivating scenario :

Present each item that represents a new term that the motivating scenario is going to introduce and definitions. The syntax is the following: new term : definition of the term

Competency questions

Please follow the following syntax for competency questions

identifier: 1
question: ** Question  **
outcome: ** The result of your question **
exemplar_answers: 
|- ** Example of answers **

** name of file of the motivating scenario ; ** 
  -  
depends_on: []

(...)

Formal description

Please give the formal SPARQL request

cq: ** identifier of the competency question it **
query: |-
 ** Example : SELECT ?workspace ?agent WHERE { ?workspace hmas:hosts ?agent } **
output: ** Result :  { (<w>,<a>) s.t.<w> hmas:hosts <a>  }  **

Please give an expected outcome

Link to query the related issues

Please use the search box to generate a link to the list of related issues. Replace the following text by : (1) name of the scenario file that will be created and (2) the url to refer to related issues

Name of your motivating scenario : related issues to /scenarios/name-of-your-motivating-scenario-that-will-be-created.md

DrLeturc commented 1 year ago

(New version to discuss)

Title of the issue = "short sentence for the story" + ":" + "features represented by the scenario by keywords e.g. norms, obligation, ... "

The new template = ...

Description

The short story...

Competency Questions

ID	Question in natural language
q1	CQ1 ?
q2	...

Glossary

Term: Short definition of the term..
...

TBox

...

ABox

...

Recommendations

...

Formal competency questions

Q1

SPARQL QUERY

Q2

...

Questions / Comments

Some questions raised by the motivating scenario to discuss in the issue ? (if there exists...)