Expand README

Author: karnkaul

README.md

@@ -1,3 +1,29 @@
 # Learn Vulkan
 
 [![Build status](https://github.com/cpp-gamedev/learn-vulkan/actions/workflows/ci.yml/badge.svg)](https://github.com/cpp-gamedev/learn-vulkan/actions/workflows/ci.yml)
+
+This repository hosts the [learn-vulkan](https://cpp-gamedev.github.io/learn-vulkan/) guide's C++ source code. It also hosts the sources of the [guide](./guide) itself.
+
+## Building
+
+### Requirements
+
+- CMake 3.24+
+- C++23 compiler and standard library
+- [Linux] [GLFW dependencies](https://www.glfw.org/docs/latest/compile_guide.html#compile_deps_wayland) for X11 and Wayland
+
+### Steps
+
+Standard CMake workflow. Using presets is recommended, in-source builds are not recommended. See the [CI script](.github/workflows/ci.yml) for building on the command line.
+
+## Branches
+
+1. `main`^: latest, stable code (builds and runs), stable history (never rewritten)
+1. `production`^: guide deployment (live), stable code and history
+1. `section/*`^: reflection of source at the end of corresponding section in the guide, stable code
+1. `feature/*`: potential upcoming feature, shared contributions, stable history
+1. others: unstable
+
+_^ rejects direct pushes (PR required)_
+
+[Original Repository](https://github.com/cpp-gamedev/learn-vulkan)

guide/src/README.md

@@ -1,6 +1,6 @@
 # Introduction
 
-Vulkan is known for being explicit and verbose. But the _required_ verbosity has steadily reduced with each successive version, its new features, and previous extensions being absorbed into the core API. Similarly, RAII has been a pillar of C++ since its inception, yet most Vulkan guides do not utilize it, instead choosing to "extend" the explicitness by manually cleaning up resources.
+Vulkan is known for being explicit and verbose. But the _required_ verbosity has steadily reduced with each successive version, its new features, and previous extensions being absorbed into the core API. Similarly, RAII has been a pillar of C++ since its inception, yet most existing Vulkan tutorials do not utilize it, instead choosing to "extend" the explicitness by manually cleaning up resources.
 
 To fill that gap, this guide has the following goals:
 
@@ -10,6 +10,8 @@ To fill that gap, this guide has the following goals:
 
 To reiterate, the focus is _not on performance_, it is on a quick introduction to the current standard multi-platform graphics API while utilizing the modern paradigms and tools (at the time of writing). Even disregarding potential performance gains, Vulkan has a better and more modern design and ecosystem than OpenGL, eg: there is no global state machine, parameters are passed by filling structs with meaningful member variable names, multi-threading is largely trivial (yes, it is actually easier to do on Vulkan than OpenGL), there are a comprehensive set of validation layers to catch misuse which can be enabled without _any_ changes to application code, etc.
 
+For an in-depth Vulkan guide, the [official tutorial](https://docs.vulkan.org/tutorial/latest/00_Introduction.html) is recommended. [vkguide](https://vkguide.dev/) and the original [Vulkan Tutorial](https://vulkan-tutorial.com/) are also very popular and intensely detailed.
+
 ## Target Audience
 
 The guide is for you if you:
@@ -30,4 +32,3 @@ Some examples of what this guide _does not_ focus on:
 ## Source
 
 The source code for the project (as well as this guide) is located in [this repository](https://github.com/cpp-gamedev/learn-vulkan). A `section/*` branch intends to reflect the state of the code at the end of a particular section of the guide. Bugfixes / changes are generally backported, but there may be some divergence from the current state of the code (ie, in `main`). The source of the guide itself is only up-to-date on `main`, changes are not backported.
-