Skip to content
This repository has been archived by the owner on Oct 3, 2023. It is now read-only.

Move from a single monolithic README to a wiki #44

Open
cyrille-artho opened this issue Feb 26, 2019 · 1 comment
Open

Move from a single monolithic README to a wiki #44

cyrille-artho opened this issue Feb 26, 2019 · 1 comment
Labels
good first issue Good for newcomers

Comments

@cyrille-artho
Copy link
Owner

cyrille-artho commented Feb 26, 2019

Currently, Modbat has only a README as documentation. This file is becoming too long, so the contents should be split up into a wiki with multiple pages.
There are also many aspects of Modbat that are not fully documented, or not documented at all in the README; some aspects are documented only in research papers. It is time to pull all that information together and present it in a unified, accessible way.

The overall structure of the README is quite good, but it is far too long now. The README should be kept with information on installing and starting the tool, but any details should be moved to a wiki.

The envisioned structure of the wiki:

  • Title
  • Summary
  • Installation
  • An introduction to model-based testing in general: This is not in the README, but several research publications and presentations have this information. The task is to provide an abridged introduction about the concepts, with references to literature, and examples (as graphical models) that illustrate the concepts.
  • Key syntax
  • Basic usage; how to compile your own model
  • How to read the error traces
  • Link to the first Modbat tutorial. The tutorial should be merged with the main wiki; its documentation (README) should also be split into multiple steps, each on its own wiki page. Besides the problem, some hints to the solution should be given, so someone who uses this for self-study finds the material more accessible. Finally, a few more advanced examples should be included, to show other features.
  • Semantics of the models
  • Preconditions and assertions
  • Inheritance
  • Advanced features. Some of them are documented in the README, others in papers, others not yet at all.
  • Exceptional outcomes should be defined conceptually and then syntactically, building on the definitions of the SEFM paper.
  • API functions
  • Observer models
  • Helper method annotations
  • Field annotations
  • Visualization
  • Replaying traces
  • Other test configuration options
  • Troubleshooting
  • Contributing to Modbat: coding conventions, self-test framework
@wruiwr
Copy link
Collaborator

wruiwr commented Aug 21, 2019

There is a wiki I created, waiting to change and move things from README.
I have briefly added "Visualization for Execution Paths" to the wiki.
I will also do something about it if I have some extra time.

@cyrille-artho cyrille-artho added the good first issue Good for newcomers label Mar 11, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
good first issue Good for newcomers
Projects
None yet
Development

No branches or pull requests

2 participants