Improve readme

Author: wenli-cai

workflow-trace-viewer/README.md

@@ -1,6 +1,8 @@
 # Workflow Trace Viewer
 
-A Compose for Desktop app that can be used to view Workflow traces.
+A Compose for Desktop application that visualizes and debugs Workflow execution traces. This tool
+helps developers understand the hierarchical structure and execution flow of their Workflow
+applications by providing both file-based and live streaming trace visualization.
 
 ## Running
 
@@ -10,20 +12,75 @@ It can be run via Gradle using:
 ./gradlew :workflow-trace-viewer:run
 ```
 
-By Default, the app will be in file parsing mode, where you are able to select a previously recorded workflow trace file for it to visualize the data.
+## Usage Guide
 
-By hitting the bottom switch, you are able to toggle to live stream mode, where data is directly pulled from the emulator into the visualizer. A connection can only happen once. If there needs to be rerecording of the trace, the emulator must first be restarted, and then the app must be restarted as well. This is due to the fact that any open socket will consume all render pass data, meaning there is nothing to read from the emulator.
+By default, the app will be in file parsing mode, where you are able to select a previously recorded
+workflow trace file for it to visualize the data. Once the workflow tree is rendered
+in [File](#file-mode) or [Live](#live-mode) mode, you can switch frames (
+see [Terminology](#Terminology)) to see different events that fired. All nodes are color coded based
+on what had happened during this frame, and a text diff will show the specific changes. You can open
+the right node panel and left click a box get a more detailed view of the specific node, or right
+click to expand/collapse a specific node's children.
 
-It is ***important*** to run the emulator first before toggling to live mode.
+<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/demo.gif" width="320" alt="Demo" />
+
+#### File Mode
+
+Once a file of the live data is saved, it can easily be uploaded to retrace the steps taken during
+the live session. Currently, text/json files that are saved from recordings only contain raw data,
+meaning it is simply a list of lists of node renderings.
+
+<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/file_mode.gif" width="320" alt="File Mode" />
+
+#### Live Mode
+
+By hitting the bottom switch, you are able to toggle to live stream mode, where data is directly
+pulled from the emulator into the visualizer. To do so:
+
+1. Start the app (on any device)
+2. Start the app, and toggle the switch to enter Live mode
+3. Select the desired device
+
+Once in Live mode, frames will appear as you interact with the app. You may also save the current
+data into a file saved in `~/Downloads` to be used later (this action will take some time, so it may
+not appear immediately)
+
+Render pass data is passively stored in a buffer before being sent to the visualizer, so you do not
+need to immediately open/run the app to "catch" everything. However, since the the buffer has
+limited size, it's strongly recommended to avoid interacting with the app — beyond starting it —
+before Live mode has been triggered; this helps to avoid losing data.
+
+<img src="https://github.com/square/workflow-kotlin/raw/wenli/improve-visualizer/workflow-trace-viewer/docs/live_mode.gif" width="320" alt="Live Mode" />
+
+### Note
+
+A connection can only happen once. There is currently no support for a recording of the trace data
+due to the fact that an open socket will consume all render pass data when a connection begins. To
+restart the recording:
+
+1. (optional) Save the current trace
+2. Switch out of Live mode
+3. Restart the app
+4. Switch back to Live mode, and the
 
 ### Terminology
 
-**Trace**: A trace is a file — made up of frames — that contains the execution history of a Workflow. It includes information about render passes, how states have changed within workflows, and the specific props being passed through. The data collected to generate these should be in chronological order, and allows developers to step through the process easily.
+`Trace`: A trace is a file — made up of frames — that contains the execution history of a Workflow.
+It includes information about render passes, how states have changed within workflows, and the
+specific props being passed through.
 
-**Frame**: Essentially a "snapshot" of the current "state" of the whole Workflow tree. It contains relevant information about the changes in workflow states and how props are passed throughout.
+`Frame`: Essentially a "snapshot" of the current "state" of the whole Workflow tree. It contains
+relevant information about the changes in workflow states and how props are passed throughout.
 
-- Note that "snapshot" and "state" are different from `snapshotState` and `State`, which are idiomatic to the Workflow library.
+- Note that "snapshot" and "state" are different from `snapshotState` and `State`, which are
+  idiomatic to the Workflow library.
 
 ### External Libraries
 
-[FileKit](https://github.com/vinceglb/FileKit) is an external library made to apply file operations on Kotlin and KMP projects. It's purpose in this app is to allow developers to upload their own json trace files. The motivation for its use is to quickly implement a file picker.
+[FileKit](https://github.com/vinceglb/FileKit) is an external library made to apply file operations
+on Kotlin and KMP projects. This simplified the development process of allowing file selection
+
+## Future
+
+This app can be integrated into the process of anyone working with Workflow, so it's highly
+encouraged for anyone to make improvements that makes their life a little easier using this app.