improve readme

README.md

@@ -1,16 +1,25 @@
+# bfabricPy
+
 [![PR Checks](https://github.com/fgcz/bfabricPy/actions/workflows/run_unit_tests.yml/badge.svg)](https://github.com/fgcz/bfabricPy/actions/workflows/run_unit_tests.yml)
 [![Nightly Integration Tests](https://github.com/fgcz/bfabricPy-tests/actions/workflows/nightly_tests.yml/badge.svg)](https://github.com/fgcz/bfabricPy-tests/actions/workflows/nightly_tests.yml)
 [![EDBT'10](https://img.shields.io/badge/EDBT-10.1145%2F1739041.1739135-brightgreen)](https://doi.org/10.1145/1739041.1739135)
 [![JIB](https://img.shields.io/badge/JIB-10.1515%2Fjib.2022.0031-brightgreen)](https://doi.org/10.1515/jib-2022-0031)
 
-# bfabricPy
-
-This package connects the [bfabric](https://fgcz-bfabric.uzh.ch/bfabric/) system to the [python](https://www.python.org/) and [R](https://cran.r-project.org/) world while providing a JSON and REST interface using [Flask](https://www.fullstackpython.com).
-The [bfabricShiny](https://github.com/cpanse/bfabricShiny) R package is an extension and provides code snippets and sample implementation for a seamless R shiny bfabric integration.
-For more advanced users the *bfabricPy* package also provides a powerful query interface on the command-line though using the provided scripts.
+## Documentation
 
 You can find the up-to-date documentation at [https://fgcz.github.io/bfabricPy](https://fgcz.github.io/bfabricPy).
 
-# Howto cite?
+## Introduction
+
+This package implements a Python interface to the [B-Fabric](https://fgcz-bfabric.uzh.ch/bfabric/) system.
+Several pieces of functionality are available:
+
+- Python API:
+    - General client for all B-Fabric web service operations (CRUD) and configuration management.
+    - A relational API for low-boilerplate read access to the B-Fabric system.
+- Scripts: Several scripts we use more or less frequently to interact with the system.
+- A REST API: A REST API to interact with the B-Fabric system. This allows us to interact with B-Fabric from R using [bfabricShiny](https://github.com/cpanse/bfabricShiny).
+
+## Howto cite?
 
 Panse, Christian, Trachsel, Christian and Türker, Can. "Bridging data management platforms and visualization tools to enable ad-hoc and smart analytics in life sciences" Journal of Integrative Bioinformatics, 2022, pp. 20220031. [doi: 10.1515/jib-2022-0031](https://doi.org/10.1515/jib-2022-0031).

docs/index.md

@@ -1,8 +1,13 @@
 # Home
 
-This package connects the [bfabric](https://fgcz-bfabric.uzh.ch/bfabric/) system to the [python](https://www.python.org/) and [R](https://cran.r-project.org/) world while providing a JSON and REST interface using [Flask](https://www.fullstackpython.com).
-The [bfabricShiny](https://github.com/cpanse/bfabricShiny) R package is an extension and provides code snippets and sample implementation for a seamless R shiny bfabric integration.
-For more advanced users the *bfabricPy* package also provides a powerful query interface on the command-line though using the provided scripts.
+This package implements a Python interface to the [B-Fabric](https://fgcz-bfabric.uzh.ch/bfabric/) system.
+Several pieces of functionality are available:
+
+- Python API:
+    - General client for all B-Fabric web service operations (CRUD) and configuration management.
+    - A relational API for low-boilerplate read access to the B-Fabric system.
+- Scripts: Several scripts we use more or less frequently to interact with the system.
+- A REST API: A REST API to interact with the B-Fabric system. This allows us to interact with B-Fabric from R using [bfabricShiny](https://github.com/cpanse/bfabricShiny).
 
 Please see below for how to install bfabricPy.