Improve documentation in README

See merge request !1148

README.md

@@ -20,7 +20,7 @@ You can find a detailed manual to install all necessary tools at our [Wiki](http
 There you can also find some tutorials to get to know the SDN controller:
 - [Lab00 education](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab00-education), which is used in education
 - [Lab00](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab00), which uses servers with gNMI targets instead of Arista switch images (needs less storage than Lab01)
-- [Lab01](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab01), which uses servers with Arista switch images (needs less storage than Lab01)
+- [Lab01](https://code.fbi.h-da.de/danet/gosdn/-/wikis/Labs/Lab01), which uses servers with Arista switch images
 ---
 ## Table of Contents
 
@@ -72,6 +72,10 @@ A simple showcase how the controller can be addressed after
   on them. They are currently unsupported.
 - `controller` represents the `goSDN-controller`.
 
+---
+
+## Concepts
+
 <div align="center" style="margin-bottom:3em; margin-top:4em">
   <img src="documentation/figures/overview/updated_controller_architecture_overview.drawio.png" />
     <p> Overview of the controller architecture</p>
@@ -87,15 +91,27 @@ A simple showcase how the controller can be addressed after
   <p> Detailed view of plugin mechanism</p>
 </div>
 
----
-
-## Concepts
+### Nucleus
 
 The `goSDN` controllers core - also called `nucleus` - is a lightweight library
 that manages principal network domains and provides southbound interface
 operations for managed network elements.
 
-In addition, we provide a simple Northbound-API (gRPC) for the controller [right here](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/controller/api).
+### Principal Networking Domain (PND)
+
+The PND is the single source of truth within a network. Its state is held and
+maintained by the controller. Any configuration of an MNE has to be applied by
+the PND.
+
+### Managed Network Element (MNE)
+
+Any network element directly configured by `goSDN`
+
+### Northbound Interface (NBI)
+
+The NBI is implemented using gRPC which means one can interact with the controller with any language that supports gRPC when using our own [proto definitions](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/api/proto/gosdn).
+
+In addition, we provide a simple abstraction layer of the Northbound-API to use with the controller in Go [right here](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/controller/api).
 
 To use the API, you can build a login method as is done in the `inventory-manager` in `utils.go`.
 You log in, create a session context with the returned token, then you can simply make API calls with this context.
@@ -120,7 +136,7 @@ func createContextWithAuthorization(sessionToken string) context.Context {
 }
 ```
 
-The code in your app:
+An example on how the code in your app to register a MNE in the controller could look like:
 ```golang
 import "code.fbi.h-da.de/danet/gosdn/controller/api"
 
@@ -130,20 +146,11 @@ ctx := createContextWithAuthorization(sessionToken)
 _, err := api.AddNetworkElement(i.sessionContext, i.controllerAddress, networkElement.Name, networkElement.UUID, &transportOptions, pluginUUID, pndUUID, []string{})
 ```
 
+The gRPC services can also be reached using HTTP requests via the gRPC-Gateway. The fitting OpenAPI definitions can be found [here](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/api/openapiv2?ref_type=heads).
 
-The gRPC services can also be reached using HTTP requests via the gRPC-Gateway. The fitting OpenAPI definitions can be found [here](https://code.fbi.h-da.de/danet/gosdn/-/tree/master/api/openapiv2?ref_type=heads). Note, that this is experimental and tested less well. If you want to use the controller in secure mode which implies it's mandatory to login and provide the received token in other requests via the HTTP header with the key-value pair:
+Note, that this is experimental and tested less well. If you want to use the controller in secure mode it is mandatory to login and provide the received token in other requests via the HTTP header with the key-value pair:
 `"authorize: token"`.
 
-### Principal Networking Domain (PND)
-
-The PND is the single source of truth within a network. Its state is held and
-maintained by the controller. Any configuration of an MNE has to be applied by
-the PND.
-
-### Managed Network Element (MNE)
-
-Any network element directly configured by `goSDN`
-
 ---
 ## Launch goSDN Controller local
 In this chapter, you learn how to launch the goSDN controller.
@@ -152,11 +159,9 @@ Firstly, make sure that you're located in the root directory of goSDN.
 `goSDN` provides a `Makefile` for all common use cases.
 
 ```sh
-# build the application files for goSDN, cSBI orchestrator, gosdnc (CLI).
-make build
+# build the application files for goSDN, cSBI orchestrator (currently not in use), gosdnc (CLI).
 
-# build the Dockerfiles for goSDN, cSBI orchestrator, gosdnc (CLI).
-make containerize-all
+make build
 ```
 
 Depending on how you want to use the controller, you might need to edit the example config files and provide the path to this or a new config file.
@@ -175,12 +180,20 @@ running `./gosdn` from the shell:
 
 ---
 
-## Getting Started
+## Getting Started using containers
 
 If you want to use the [playground](#playground) you have to make sure you
 have [containerlab](https://containerlab.dev/install/) installed on your
 system.
 
+It is possible to build all the docker containers using the following command from the root directory of the project:
+```sh
+# build the Docker containers for goSDN, cSBI orchestrator (currently not in use), gosdnc (CLI) as well as some of the provided example applications.
+make containerize-all
+```
+
+Note that this command is included as a step when using any of the following enviroments like the playgrounds, labs etc. and therefore can be skipped.
+
 ### Playground
 
 With the help of [containerlab](https://containerlab.dev/) we provide simple test environments to play around with.