Merge pull request #23629 from vespa-engine/kkraune/readme-fix

Add logo, misc cleanup

2 files changed, 59 insertions, 24 deletions

diff --git a/client/README.md b/client/README.md
index a459ea65b1d..8403e02a485 100644
--- a/client/README.md
+++ b/client/README.md
@@ -1,19 +1,45 @@
 <!-- Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. -->
 
+![Vespa logo](https://vespa.ai/assets/vespa-logo-color.png)
+
 # Vespa clients
+This part of the Vespa repository got Vespa client implementations for operations like
+* deploy
+* read/write
+* query
+
+<!-- ToDo: illustration -->
+
+
 
 ## Vespa CLI
 The Vespa command-line tool, see the [README](go/README.md).
+Use the Vespa CLI to deploy, feed and query a Vespa application,
+for local, self-hosted or [Vespa Cloud](https://cloud.vespa.ai/) instances.
+
+
+
+## pyvespa
+[pyvespa](https://pyvespa.readthedocs.io/) provides a python API to Vespa -
+use it to create, modify, deploy and interact with running Vespa instances.
+The main pyvespa goal is to allow for faster prototyping
+and to facilitate Machine Learning experiments for Vespa applications.
+
 
 
 ## Vespa FE (fixme: better name and description here)
-This is a work-in-progress javascript app for various use cases.
+This is a [work-in-progress javascript app](js/app) for querying a Vespa application.
+
 
 
-## vespa_query_dsl
+----
+
+## Misc
+
+<!-- ToDo: move this / demote this somehow -->
+### vespa_query_dsl
 This lib is used for composing Vespa
 [YQL queries](https://docs.vespa.ai/en/reference/query-language-reference.html).
-
 For usage, refer to the [QTest.java](src/test/java/ai/vespa/client/dsl/QTest.java) unit test.
 
 ToDos:
diff --git a/client/js/app/README.md b/client/js/app/README.md
index 99271629edf..ae6a8d1cc25 100644
--- a/client/js/app/README.md
+++ b/client/js/app/README.md
@@ -1,48 +1,57 @@
 <!-- Copyright Yahoo. Licensed under the terms of the Apache 2.0 license. See LICENSE in the project root. -->
 
+![Vespa logo](https://vespa.ai/assets/vespa-logo-color.png)
+
 # Vespa client
 
 This app is work in progress.
+It currently contains the **Query Builder** and the **Trace Visualizer**.
+
 
-This client currently contains the **Query Builder** and the **Trace Visualizer**.
 
-# Query Builder
+## Query Builder
+The Query Builder is a tool for creating Vespa queries to send to a local backend.
+The tool provides all of the options for query parameters from dropdowns.
+The input fields provide hints to what is the expected type of value.
 
-The Query Builder is a tool for creating Vespa queries to send to a local backend.  
-The tool provides all of the options for query parameters from dropdowns. The input fields  
-provide hints to what is the expected type of value.
 
-# Trace Visualizer
 
-The Trace Visualizer is a tool for converting and visualizing traces from Vespa in a flame graph.  
-To use the visualizer, a [Jaeger](https://www.jaegertracing.io/) instance must be run locally with Docker.
+## Trace Visualizer
+The Trace Visualizer is a tool for converting and visualizing traces from Vespa in a flame graph.
+To use the visualizer, a [Jaeger](https://www.jaegertracing.io/) instance must be run locally with Docker:
 
     docker run -d --rm \
-    -p 16685:16685 \
-    -p 16686:16686 \
-    -p 16687:16687 \
-    -e SPAN_STORAGE_TYPE=memory \
-    jaegertracing/jaeger-query:latest
+      -p 16685:16685 \
+      -p 16686:16686 \
+      -p 16687:16687 \
+      -e SPAN_STORAGE_TYPE=memory \
+      jaegertracing/jaeger-query:latest
 
 The Jaeger UI can then be reached at **localhost:16686/search**
 
-To use the visualizer you paste the Vespa trace into the text box and press the button to convert the trace  
-to a format supported by Jaeger and download it.  
-Only Vespa traces using _trace.timestampa=true_ **and** _traceLevel_ between 3 and 5 (inclusive) will work correctly.
+To use the visualizer,
+paste the Vespa trace into the text box
+and press the button to convert the trace to a format supported by Jaeger and download it.
+Only traces using _trace.timestamps=true_ **and** _traceLevel_ between 3 and 5 (inclusive) will work correctly -
+see [query tracing](https://docs.vespa.ai/en/query-api.html#query-tracing):
 
 ![Trace Converter](img/TraceConverter.png)
 
-After downloading the converted trace is can be used with the Jaeger UI.  
-Press the _JSON File_ button as shown in the image, and drag and drop the trace you just downloaded.
+After downloading the converted trace, it can be used with the Jaeger UI. 
+Press the _JSON File_ button as shown in the image, and drag and drop the trace you just downloaded:
 
-![Jager Image](img/JaegerExample.png)
+![Jaeger Image](img/JaegerExample.png)
 
-You can then click on the newly added trace and see it displayed as a flame graph.
+Then click on the newly added trace and see it displayed as a flame graph:
 
 ![Example Image](img/result.png)
 
-# Client install and start
+
+
+## Client install and start
 
     nvm install --lts node  # in case your current node.js is too old
     yarn install
     yarn dev                # then open link, like http://127.0.0.1:3000/
+
+<!-- ToDo: publish a Docker image with all the clients ... -->