Readme improvements (elisa-tech#25)

* Added mission statement Nowcomer onboarding checklist Some general fleshing out and improvements Signed-off-by: Jochen Kall <[email protected]> * General fleshing out Added newcomer onboarding checklist Signed-off-by: Jochen Kall <[email protected]> * Architectur Workgroup-> Safety Architecture Workgroup Signed-off-by: Jochen Kall <[email protected]>
FlorianGuenther2 · Apr 4, 2022 · f95a4db · f95a4db
1 parent db6427e
commit f95a4db
Show file tree

Hide file tree

Showing 2 changed files with 63 additions and 24 deletions.
diff --git a/README.md b/README.md
@@ -1,53 +1,89 @@
-# ELISA Automotive WG - Navigation and file locations
-## Mailing list, Calendar etc
+# ELISA Automotive WG
+## Mission statement
+The automotive workgroup discusses the conditions and prerequisites the automotive sector needs to integrate Linux into a safety critical system.
+
+We focus on actual use cases from the Automotive domain to derive the technical requirements to the kernel as a basis for investigation within the Safety Architecture Workgroup and to serve as a blueprint for actual projects in the future.
+
+This repository contains aggreed upon and peer reviewed material for this work group, see [process description below](#contribution-workflow)
+
+## Use case
+Currently, the Automotive work group focuses on the telltale use case, i.e. warning symbols in the intstrument cluster of a car, targeting ASIL B.
+## Getting in Contact, Getting Involved
+### Mailing list, Calendar etc
+Subscribe to our mailing list:
 https://lists.elisa.tech/g/automotive
-## Meeting Minutes
+
+### Meetings
+The Automotive workgroup currently meets twice a week
+* Friday 14:00 CET: General sync call
+* Thursday 9:00 CET: Working session
+
+Note that the web calendar associated with our mailing list contains up to date information about all workgroup meetings, consider subscribing to keep up to date!
+
+Our meeting minutes are kept at 
 https://docs.google.com/document/d/1qgEkB6HBjq0ojoTSmI_E18BZco3lORK1ZZDrBH1YQo0/edit#heading=h.b7qah2h40uzb
+
+### Newcomer Onboarding Checklist
+If you are new and all this seems overwhelming, don't fret, we got you covered!
+
+Single most important instruction: drop by the workgroup and ask, despite our effort not everything can be always kept up to date.
+
+Other than that, here is a checklist to get you started:
+* Sign up for [mailinglist and calendar](#mailing-list-calendar-etc)
+* familiarize yourself with our tooling for [modelling and requirements](#tooling)
+* Get to know the [contribution process](#contribution-workflow)
+* Check out this repository and explore, [Repo overview](#elisa-automotive-wg---navigation-and-file-locations)
+* Check out the meeting minutes and drop by our [weekly sync call](#meetings) 
+* [Developers] check out the meta-elisa repository to learn how to set up a build environment, build and run the [demo](#first-iteration-of-the-use-case)
+
+# ELISA Automotive WG - Navigation and file locations
 ## Google drive workgroup folder
+The google drive is used for drafts, presentation and general material that has to be considered work in process. The gdrive also is used for the meeting minutes.  
 https://drive.google.com/drive/folders/1FCEzywCMfk3wY6lxBoMYjfQ_DQ44S5YS
 ## Repo Orientation regarding the Telltale Usecase
-### Original considerations of the Use Case can be found in the folder 
-Initialy_discussed_system_scope
-### The First iteration of the use case that the meta-elisa demo is based on can be found in
-AGL_cluster_demo_use_case
+### Original considerations
+The originial considerations of the Use Case can be found in the subfolder "Initialy_discussed_system_scope" of this repository
+### First iteration of the use case
+The first iteration of the use case, that the meta-elisa demo is based on, can be found in the subfolder "AGL_cluster_demo_use_case" of this repository
 * Item definition
 * Safety Concept/Requirements
-Our Implementation on top of the AGL Cluster demo is split in two repositories:
-
-The meta layer: (also includes build and running instructions)
-
-https://github.com/elisa-tech/meta-elisa
-
-The true sourcecode repository:
 
-https://github.com/elisa-tech/wg-automotive-safety-app
+Our Implementation on top of the preexisting AGL Cluster demo is split in two repositories:
+* The meta layer: (also includes build and running instructions)
+  * https://github.com/elisa-tech/meta-elisa
+* The sourcecode repository providing the actual code:
+  * https://github.com/elisa-tech/wg-automotive-safety-app
 
-### The second iteration of the use case including Eclipse Papyrus based SysML models can be found in
-Cluster_Display_Use_Case_v2
+### Second iteration of the use case
+The second iteration of the use case including Eclipse Papyrus based SysML models and the ongoing STPA analysis can be found in the subfolder "Cluster_Display_Use_Case_v2"
 * Item definition [WIP]
 * SysML models [WIP]
+* STPA analysis [WIP]
 
 The models are also visible via github page deployment as online viewer at:
 
 https://elisa-tech.github.io/wg-automotive/
 
 The html export might not always be up to date with the models, generation is not automated (yet)
-## Tooling
-### Requirements
-Requirements are stored and handled as Freeplane Mindmap with Functional Safety Addon
+
+# Tooling
+## Requirements
+Requirements and Safety concepts are stored and handled as Freeplane Mindmap using the Functional Safety Addon specifically developed for the task.
 * https://www.freeplane.org/wiki/index.php/Home
 * https://github.com/Jochen-Kall/Safety_concept_tool
-### SysML modeling
+
+![Mindmap Example](documentation/Example_requirements.png)
+## SysML modeling
 SysML models are done with Eclipse Papyrus with SysML v1.6 Plugin
 * https://www.eclipse.org/papyrus/
 * https://marketplace.eclipse.org/content/papyrus-sysml-16
 
-## Contribution workflow
+# Contribution workflow
 To make collaboration as frictionless as possible, the automotive workgroup uses the following github based workflow.
-### Prerequisites
+## Prerequisites
 * Git
 * Github account
-### Workflow
+## Workflow
 * If you did not fork and clone yet
   * Fork the upstream repo and clone your fork to get a local working copy, details see [click](#initial-setup---forking-and-cloning)
 * If you already forked the repository and cloned your fork
@@ -70,6 +106,9 @@ If you did create an issue, it is best practice to reference the issue in your c
   * Merge ready Pullrequests are put on the next Workgroup synccall agenda for discussion, if consensus is found, the pullrequest is merged by an maintainer.
 
 # Git Newbie section
+This section serves as reference for members new to GIT, to be read on demand.
+All the GIT black belts out there can stop reading at this point in good concience. 
+
 ## Intital Setup - Git etc
 For this workflow, having Git installed and configured is essential. 
 

diff --git a/documentation/Example_requirements.png b/documentation/Example_requirements.png