Update documentation.

- Update readme to fill out some of the `TODO` sections

- Add an API user's guide that gives the basics of linking against Slang and using it to compile and reflect shaders

- Add a bit of usage info for the command-line `slangc` program

- Add an overview of the Slang language as it stands today

- Add an initial FAQ, mostly to help answer the "why should I use this?" question

1 files changed, 82 insertions, 14 deletions

diff --git a/README.md b/README.md
index 33bff684c..8125dbd38 100644
--- a/README.md
+++ b/README.md
@@ -2,39 +2,107 @@
 
 [![AppVeyor build status](https://ci.appveyor.com/api/projects/status/3jptgsry13k6wdwp/branch/master?svg=true)](https://ci.appveyor.com/project/shader-slang/slang/branch/master)
 
-Slang is a library for compiling real-time shader code.
-It can be used with either existing HLSL or GLSL code, or with code written directly in Slang.
-The library provides a variety of services that application developers can use to put together the shader compilation workflow they want.
+Slang is a library and a stand-alone compiler for wroking with real-time shader code.
+It can be used with existing HLSL or GLSL code, but also supports a new HLSL-like shading language, also called Slang.
+The library provides a variety of services that support applications in putting together their own shader compilation workflows.
 
-Services provided by the Slang library include:
+Using Slang you can:
 
-* Slang can scan ordinary HLSL or GLSL code that neglects to include `register` or `layout` bindings and "rewrite" that code to include explicit bindings for all shader parameters. This lets you write simple and clean code, but still get deterministic binding locations.
+* Take ordinary HLSL or GLSL code that neglects to include all those tedious `register` and `layout` bindings, and transform it into code that includes explicit bindings on every shader parameter. This frees you to write simple and clean code, while still getting completely deterministic binding locations.
 
-* Slang provides a full reflection API for shader parameters, with a uniform interface across HLSL, GLSL, and Slang. The reflection system does not silently drop unused/"dead" parameters, and it can even be used on libraries of shader code without compiling any entry points.
+* Get full reflection information about the parameters of your shader code, with a consistent API interface across GLSL, HLSL, and Slang code. Slang doesn't silently drop unused or "dead" shader parameters from the reflection data, so you can always see the full picture.
 
-* *Work in progress:* Slang supports cross-compilation of either HLSL or Slang code to GLSL.
+* Cross-compile shader code written in the HLSL-like Slang shading language to HLSL, GLSL, DX bytecode, or SPIR-V. You can even write ordinary HLSL or GLSL by hand that makes use of libraries of code written in Slang.
 
-* You can directly get HLSL or GLSL source code as output from Slang, or you can let the library invoke lower-level code generation for you to get back DXBC or SPIR-V (DXIL support to come).
+## Getting Started
+
+There are several ways that you can get started using Slang, depending on how complex your application's needs are.
+
+Right now Slang only supports Windows builds (32- and 64-bit).
+
+### Binary releases
+
+Pre-built binary packages for the stand-alone Slang compiler and a DLL of the Slang library are available through GitHub [releases](https://github.com/shader-slang/slang/releases).
+
+### Building from source
+
+If you would like to build Slang from source, then clone [this](https://github.com/shader-slang/slang) repository, and then run:
+
+    git submodule update --init
+
+Next, open `slang.sln` and build your desired platform/configuration.
+
+### Integrating the source into your build
+
+If you want to statically link Slang into your application, instead of having to deal with a dynamic library, then the easiset option is to just integrate Slang into your build.
+
+First, clone the Slang repostiory (or download a source [release](https://github.com/shader-slang/slang/releases)) and add the root folder of the slang repository/release to your include path.
+Then in one `.cpp` file in your project, write:
+
+```c++
+#define SLANG_INCLUDE_IMPLEMENTATION
+#include <slang.h>
+```
+
+This causes the `slang.h` header to `#include` all the source files that make up the Slang compiler implementation.
+
+Note that this option does *not* currently include support for generating SPIR-V output, unless you build the `slang-glslang` dynamic library separately.
 
 ## Documentation
 
-TODO
+The Slang [language guide](docs/language-guide.md) provides information on extended language features that Slang provides for user code.
 
-## Getting Started
+The [API user's guide](docs/api-users-guide.md) gives information on how to drive Slang programmatically from an application.
+
+If you want to try out the `slangc` command-line tool, then you will want to read its [documentation](docs/command-line-slangc.md).
+Be warned, however, that the command-line tool is primarily intended for experimenting, testing, and debugging; serious applications will likely want to use the API interface.
+
+## Limitations
+
+The Slang project is in a very early state, so there are many rough edges to be aware of.
+Slang is *not* currently recommended for production use.
+The project is intentionally on a pre-`1.0.0` version to reflect the fact that interfaces and features may change at any time (though we try not to break user code without good reason).
+
+Major limitations to be aware of (beyond everything files in the issue tracker):
+
+* Slang only supports outputting GLSL/SPIR-V for Vulkan, not OpenGL
+
+* Slang's current approach to automatically assigning registers is appropriate to D3D12, but not D3D11
 
-TODO
+* Slang-to-GLSL cross-compilation only supports vertex, fragment, and compute shaders. Geometry and tessellation shader cross-compilation is not yet implemented.
 
-## Testing
+* The Slang front-end does best-effort checking of HLSL input, and only supports very minimal checking of GLSL. When using these languages, the `-no-checking` option can be used to allow Slang to work with these files even when it gets confused by constructs it doesn't support.
 
-TODO
+* Translations from Slang/HLSL constructs to GLSL equivalents has been done on as as-needed basis, so it is likely that new users will run into unimplemented cases.
 
 ## Contributing
 
-TODO
+If you'd like to contribute to the project, we are excited to have your input.
+We don't currently have a formal set of guidelines for contributors, but here's the long/short of it:
+
+* Please follow the contributor [Code of Conduct](CODE_OF_CONDUCT.md).
+* Bugs reports and feature requests should go through the GitHub issue tracker
+* Changes should ideally come in as small pull requests on top of `master`, coming from your own personal fork of the project
+* Large features that will involve multiple contributors or a long development time should be discussed in issues, and broken down into smaller pieces that can be implemented and checked in in stages
 
 ## Contributors
 
+If you contribute changes to the library, please feel free to add (or remove/update/change) your name here.
+
 * Yong He
 * Haomin Long
 * Teguh Hofstee
 * Tim Foley
+* Kai-Hwa Yao
+
+## License
+
+The Slang code itself is under the MIT license (see [LICSENSE](LICENSE)).
+
+The Slang projet can be compiled to use the [`glslang`](https://github.com/KhronosGroup/glslang) project as a submodule (under `external/glslang`), and `glslang` is under a BSD licesnse.
+
+The Slang tests (which are not distributed with source/binary releases) include example shaders extracted from:
+* A [repository](https://github.com/SaschaWillems/Vulkan) of Vulkan GLSL shaders by Sascha Willems, which are under the MIT license
+* Sample HLSL shaders from the Microsoft DirectX SDK, which has its own licesnse
+
+Some of the Slang examples and tests use the `stb_imgae` and `stb_image_write` libraries (under `external/stb`) which have been placed in the public domain by their author(s).