Rewrite introductory documentation

Author: madsmtm

Cargo.toml

@@ -5,7 +5,7 @@ members = ["run-wasm"]
 name = "softbuffer"
 version = "0.4.8"
 edition = "2021"
-description = "Cross-platform software buffer"
+description = "Cross-platform buffer for software rendering"
 license = "MIT OR Apache-2.0"
 documentation = "https://docs.rs/softbuffer"
 repository = "https://github.com/rust-windowing/softbuffer"

README.md

@@ -1,10 +1,12 @@
 # Softbuffer
 
-Enables software rendering via drawing an image straight to a window.
+Render an image on the CPU and show it on a window in a cross-platform manner.
 
-Softbuffer integrates with the [`raw-window-handle`](https://crates.io/crates/raw-window-handle) crate
-to allow writing pixels to a window in a cross-platform way while using the very high quality dedicated window management
-libraries that are available in the Rust ecosystem.
+To use Softbuffer, first create a window using `winit`, `sdl3`, or any other crate that provides a [`raw_window_handle::HasWindowHandle`](https://docs.rs/raw-window-handle/0.6.2/raw_window_handle/trait.HasWindowHandle.html).
+
+Next, you create a [`Context`] and [`Surface`] from that window, and can now call [`Surface::buffer_mut()`] to get a [`Buffer`] that you can draw into. Once you're done drawing, call [`Buffer::present()`] to show the buffer on the window.
+
+Note that Softbuffer only provides the `&mut [...]` buffer, it does not provide any rendering primitives for drawing rectangles, circles, curves and so on. For that, you'll want to use a crate like [`tiny-skia`](https://docs.rs/tiny-skia/) or [`vello_cpu`](https://docs.rs/vello_cpu/).
 
 ## Platform support: