How to create a scenario for the SSK? (a SSK Tutorial)

The following instructions help users create a scenario for the SSK. These instructions are themselves conceived as a “scenario”, a step-by-step tutorial. First, contributors should be aware that:

  • they can submit their new scenarios directly in TEI - see The SSK data model (TEI) section - and upload them on the SSK GitHub (http://github.com/ParthenosWP4/SSK), or by using the dedicated SSK contribution workspace (still work in progress).
  • scenarios and steps follow the same data model. The difference is that a scenario points to a set of steps whereas a step points to a set of external resources.
  • It is possible to create a scenario in any language but ideally, we would advocate for at least bilingual scenarios, with an additional version in English, in order to make it more visible. The forthcoming user interface will implement such behaviour and in TEI, it is possible to translate the prose, by duplicating the elements head, desc or term, and adding xml:lang attributes.
_images/img-tuto.jpeg

Choose explicit titles starting with a verb or a gerund

The choice of good titles for a scenario and its steps is crucial. They will be the entry point for the readers, who need to understand at first reading the scope and the aim of a scenario. To ensure that the message will driven home, we advice to build titles :

  • that starts with a verb or a gerund, describing the process (for a scenario) or the action (for a step) that the user will read about;
  • with a number of characters comprised between 10 and 100.

References

Describing a scenario or a step

The description of the scenario and its steps is the longer text that the contributor has to provide.

  • For a scenario, it should explain the scientific problematic and describe the solution put in place.
  • For a step, It should describe the purpose of the action, how it relates with the previous ones and give an overall presentation of the different kind of methods and tools the resources would point to.
  • For both, it is important to extend the acronyms cited and to briefly present the projects mentioned.

The form of this text should respect the following constraints:

  • It shouldn’t exceed 1500 characters (but should not be too short either).

  • It is possible to point to external links. In TEI, use the following code:

    <ref target="//url here//">text of the link</ref>
    
  • Lists are also available. The TEI elements are <list> and <item>

References

Associate keywords to the scenario or the step

In order to enhance discoverability and search relevance, the SSK resources are described with a set of controlled vocabularies, particularly created for describing Humanities research. They are:

When editing the description of a scenario, the available keywords are:

  • Research Techniques
  • Research objects
  • Standards
  • Disciplines

For the steps, the most important keyword is the Activity, that should be unique for each step. It also possible to pick some techniques, objects and standards. For each keyword type, we recommend to choose between 1 and 4 terms.

References

Choose an illustration for the scenario

  • The illustration must closely relates with the purpose of the scenario, i.e. not only with the discipline or the period studied.
  • Screenshots are accepted.
  • Landscape orientation image are recommended
  • Maximum size : 2 Mo
  • Accepted formats : png or jpg
  • It must be published under the licence CC-BY or CC-0.

References

  • Unsplash, a gallery of free images and photos

Identify relevant resources

Identifying state of the art references is a prerequisite before actually add the resources to the steps. When we are talking about resources, we mean a standardized tool, service or document helpful for the task completion.

They take the form of a digital object and have to be of one the following types:

  • Specification (normative document) of a standard (spec);
  • Technical reports (report);
  • Scholarly papers (paper);
  • A single scholarly monograph (book);
  • Lists of bibliographic references (bibliography);
  • Scripts and code samples (code);
  • Computing libraries (library);
  • Collection of structured data (database);
  • Computing tool, software (tool);
  • Curating or hosting service (service)
  • Tutorials or guidelines (tutorial);
  • Blog posts (blog);
  • Specialised mailing list, forum, etc (community).

The resources should be separated into several groups:

  • First, general resources like standard specifications
  • Second, project-related resources, i.e. how the standards are used in a real research project.

Advanced SSK functions (1) : customize a step

The SSK is adaptable by nature and contributors don’t have to start from scratch their scenario. It is possible to create a scenario with existing steps as basis. But if the content of the step doesn’t exactly fit, it is also possible to modify it, by updating the initial step (but with care), or, more safely, directly in the new scenario.

In TEI, the update of some elements is made with the help of the attribute @mode. See more in the section: Reuse/customize a step.