[WIP] reorganize docs/

docs/README.md

@@ -4,32 +4,55 @@ Slang Documentation
 This directory contains documentation for the Slang system.
 Some of the documentation is intended for users of the language and compiler, while other documentation is intended for developers contributing to the project.
 
-Getting Started
----------------
+* historical
 
-The Slang [User's Guide](https://shader-slang.github.io/slang/user-guide/) provides an introduction to the Slang language and its major features, as well as the compilation and reflection API.
+Language
+--------
 
-There is also documentation specific to using the [`slangc`](command-line-slangc.md) command-line tool.
+The Slang language [User's Guide](https://shader-slang.github.io/slang/user-guide/) provides an introduction to the Slang language and its major features, as well as the compilation and reflection API.
 
-Advanced Users
---------------
+Work is in progress on a more detailed [reference](language/reference) for the Slang language, but that documentation is not ready for general consumption.
 
-For the benefit of advanced users we provide detailed documentation on how Slang compiles code for specific platforms.
-The [target compatibility guide](target-compatibility.md) gives an overview of feature compatibility for targets. 
+Compiler
+--------
 
-The [CPU target guide](cpu-target.md) gives information on compiling Slang or C++ source into shared libraries/executables or functions that can be directly executed. It also covers how to generate C++ code from Slang source.  
+The command-line Slang compiler, `slangc`, has its own separate [user's guide](compiler/command-line/guide) and [reference](compiler/command-line/reference).
 
-The [CUDA target guide](cuda-target.md) provides information on compiling Slang/HLSL or CUDA source. Slang can compile to equivalent CUDA source, as well as to PTX via the nvrtc CUDA complier.
+Slang Standard Library
+----------------------
 
-Contributors
-------------
+A [reference](stdlib/reference) for all of the built-in types, functions, etc. supported by Slang is generated from the content of the Slang standard library.
+The quality of this documentation is currently lacking.
 
-For contributors to the Slang project, the information under the [`design/`](design/) directory may help explain the rationale behind certain design decisions and help when ramping up in the codebase.
+Supported GPU Features
+----------------------
 
-Research
---------
+Documentation of individual GPU hardware and API features supported by Slang is organized under [`gpu-feature`](gpu-feature/).
+The documents there typically describe how a feature is exposed in the Slang standard library, how those constructs map to each of the targets that supports a given feature, and any caveats that users should be aware of.
+
+Supported Targets
+-----------------
+
+When compiling for multiple targets, the [Feature Stability Table](target/feature-stability.md) gives an overview of which targets support which GPU features.
+
+Detailed guides for individual targets are collected under [`target/`](target/).
+
+Proposals
+---------
+
+Proposals for changes to the Slang language, standard library, API, or tools are organized under [`proposals/`](proposals/).
+Proposals are used to iterate on the design of new features before they are finalized.
+
+For Contributors
+----------------
+
+For contributors to the Slang project, the information under the [`contributor/`](contributor/) directory may be relevant to building the project, interacting with our CI process, etc.
+
+In addition, the documents under [`compiler/implementation/`](compiler/implementation/) are intended to provide developers working on the project with explanations of how certain subsystems of the compiler have been designed and implemented.
+Proposals for implementation improvements and changes may be checked in under [`compiler/implementation/proposals`](compiler/implementation/proposals); these documents do *not* reflect the current status of the codebase, but may guide future development.
 
-The Slang project is based on a long history of research work. While understanding this research is not necessary for working with Slang, it may be instructive for understanding the big-picture goals of the language, as well as why certain critical decisions were made.
+The `gfx` GPU Library
+---------------------
 
-A [paper](http://graphics.cs.cmu.edu/projects/slang/) on the Slang system was accepted into SIGGRAPH 2018, and it provides an overview of the language and the compiler implementation.
-Yong He's [dissertation](http://graphics.cs.cmu.edu/projects/renderergenerator/yong_he_thesis.pdf) provided more detailed discussion of the design of the Slang system.
+The Slang system provides a (completely optional) GPU API abstraction layer, called `gfx`.
+The `gfx` library has its own [documentation](gfx), separate from the Slang language and compiler.

docs/historial/README.md

@@ -0,0 +1,13 @@
+Historical Artifacts
+====================
+
+This direction collects documentation that has been checked into the codebase at various points during development, but that is no longer relevant or accurate to the state of the project and codebase today.
+These documents are likely only of interest to those who want to piece together the history and evoution of the project.
+
+Research
+--------
+
+The Slang project is the product of a long history of research work, but the academic publications on Slang are no longer the best place to go in order to understand and use the system.
+
+A [paper](http://graphics.cs.cmu.edu/projects/slang/) on the Slang system was prestented at SIGGRAPH 2018, and it provides an overview of the language and the compiler implementation.
+Yong He's [dissertation](http://graphics.cs.cmu.edu/projects/renderergenerator/yong_he_thesis.pdf) provided more detailed discussion of the design of the Slang system.

docs/user-guide/index.md → docs/language/guide/index.md

@@ -1,13 +1,13 @@
----
-layout: user-guide
----
-
-Slang User's Guide
-=============
-
-Welcome to the Slang User's Guide, an introduction to the Slang language, compiler, and API. In this guide, you will learn:
-- Slang's language features, including those inherited from HLSL and additional language features to make it easy to work with shaders.
-- The compiler API that controls how to assemble shaders from different pieces of code, and how they are compiled for different targets.
-- The reflection API that allows the host application to query the details of shader code in order to generate the right shader kernel and to set shader parameters correctly.
-
-Note: this documentation is still under active development. While the coverage on language features is complete, we are still working on the remaining chapters on Slang's compilation and reflection API.
+---
+layout: user-guide
+---
+
+Slang User's Guide
+=============
+
+Welcome to the Slang User's Guide, an introduction to the Slang language, compiler, and API. In this guide, you will learn:
+- Slang's language features, including those inherited from HLSL and additional language features to make it easy to work with shaders.
+- The compiler API that controls how to assemble shaders from different pieces of code, and how they are compiled for different targets.
+- The reflection API that allows the host application to query the details of shader code in order to generate the right shader kernel and to set shader parameters correctly.
+
+Note: this documentation is still under active development. While the coverage on language features is complete, we are still working on the remaining chapters on Slang's compilation and reflection API.