Dev:Use cases

Guideline for use cases
 
This page should be considered as an annex to the guides of the section use-cases (link to the railML^® website). If inconsistencies are found, then guides of the section use-cases (link to the railML^® website) have higher priority.

In this page you learn, how to contribute to writing good railML^®-Use Cases.

While the emphasis of the railML^®-wiki lies in documenting single elements in a bottom-up approach, we also try to help users to capture the concepts of railML^® via examples and use cases in a top down approach.

What is a use case?

A use case can be defined as a single task, performed by the end user of a system, that has some useful outcome. It is described as a list of steps (actions or events) to achieve this outcome.

A use case in terms of railML^® is an application of data exchange between at least two IT systems in the railway domain, where railML^® can be used as a format and language for the data to be exchanged. The aim of the use case description is to formulate requirements on the technical implementation of the data exchange.

What distinguishes a use case from an example is, that examples will typically consist of pieces of railML^®-code, whereas use cases will typically be formulated in natural language or Unified Modelling Language (UML). Examples are solutions to use cases.

What makes a good use case?

A good use case should be complete, comprehensible and practically relevant. Ideally, it should be perceivable by the public (A problem that can be understood by and occur to everybody is more illustrative than one that only occurs to a small subgroup of users). Finally, the use case should be objective in the sense that it is not biased to the requirements or solutions of a certain organization or company.

Structure

Each use case is assigned to a subschema. The article name should follow the paradigm UC:<subschema>:<use case>, e.g. UC:IS:Timetabling.

Post 2023

In railML^®, use cases are usually presented with the following structure (which, too, can be seen in the example of UC:IS:RailInspectionData):

• Head/Title
• Description: A sketch of the task, the necessary steps and the requirements in general.

What is the application behind the use case? Which data in general is required? Which kind of tool/application provides this data? Who usually consumes it? Which data is not included (if not obvious)? Define the boundaries of the use case and the relevant data.

• Data flows and interfaces

Which data flows exist? How often is data exchanged? What is the granularity? How does it change over time, if it does at all? Diagrams/images would be helpful to visualize the dataflow.

• Dependent railML domains

Please describe what domains of railML the use case is dependent upon if any, e.g. infrastructure, timetable, rolling stock, interlocking. Please also clarify if this dependency is essential for the use case or considered optional.

• Characterizing data

Please describe what data is exchanged for the use case. What is part and what is not part of the data exchange. What level of detail is usually included. On what does this level of detail depend. This description is usually the starting point for the next level of determining a more formalized and detailed table of the domain elements necessary for the use case. This description may also reference other existing use cases.

• Sub-use cases

Are there any partial use cases distinguished, which build on each other?

• Additional remarks
• References

Template

If you start a new use case description you can copy the list below to support a correct structure. To get an impression how to employ the templates of this list see Dev:Use case example.

{{UseCase|<subschema>|<version>|title=|reporter=}}
{{UC title}}
{{UC description}}
{{UC flows}}
{{UC dependence}}
{{UC data}}
{{UC sub}}
{{UC remarks}}
{{UC references}}

Pre 2023

Older use cases are usually presented with the following structure (which, too, can be seen in the example of UC:IS:Timetabling):

• Head/Title
• Description: A sketch of the task, the necessary steps and the requirements in general.

It is important to note, to which railML^® versions a use case or certain aspects of it apply, as use cases will develop further with the development of railML^®.

• Data flows and interfaces
• Interference with other railML^® schemas
• Characterizing Data
  • How often do the data change (update)?
  • How big are the data fragments to be exchanged (complexity)
  • Which views are represented by the data (focus)?
  • Which specific timetable data do you expect to receive/send (elements)?

Template

If you edit an older use case, please stick to the following structure. To get an impression how to employ the templates of this list see Dev:Use case example/old.

{{UseCase|<subschema>|<version>|title=|reporter=}}
{{UC title}}
{{UC description}}
{{UC flows}}
{{UC interference}}
{{UC data}}
{{UC update}}
{{UC complexity}}
{{UC focus}}
{{UC elements}}

For information how to use Template:UseCase, see Template:UseCase#Usage. The other templates of the list work without arguments and only produce standardized chapter headlines.

How to contribute a use case

1. Please, get into contact with the coordinator of the respective subschema before you start writing a use case. Feel free to start an article in your userspace at your own risk of doing obsolete work.
2. Develop the use case according to the mentioned criteria (especially #structure and #What makes a good use case?).
3. Let the subschema coordinator review the article.
4. The subschema coordinator will take care of publishing the article. He will version the use case and match it with the railML^®-versions to which it applies — both the use case and railML^® will evolve in the course of time. Finally, the article will be entered into the use case collection of the respective subschema, as in #Lists.
5. If you feel more comfortable to submit use case using a Word file you may use a MS Word and Excel template files (link to the railML^® website)

provided by railML.org. Please sbubmit the filled document as Word file (not as PDF nor scanned image!) to the corresponding coordinator (link to the railML^® website) or the railML coordination (link to the railML^® website).