Document code structure in root readme (#2220)

And add some stub readme's

README.md

@@ -15,9 +15,17 @@ so you can focus on your app's business logic. Fluid's data synchronization is f
 bandwidth. Fluid is extensible, too. You can write components which can be re-used or you can even create new
 distributed data structures.
 
-## Installing
+## Getting started using the Fluid Framework
 
-_Coming soon._
+You may be here because you want to...
+
+- Build a Component
+- Build a Container
+- Host Fluid containers in your application
+- Develop a new DDS
+- Implement a Fluid server
+
+All of these are documented at <https://aka.ms/fluid>.
 
 ## Contributing
 
@@ -37,13 +45,32 @@ with any additional questions or comments.
 * Help each other in the [Fluid Community Discord]() **(community channel not yet created)**
 * Join the discussion on Twitter **(hashtag not established yet)**
 
-## Documentation
+## Code Structure
 
-Get up and running quickly using our documentation at <https://aka.ms/fluid>.
+The core code is built into several large chunks ("minirepos", managed using [Lerna](https://lerna.js.org/)) which are versioned separately from one another, but internally all packages in a minirepo are versioned together. And outside the minirepos there are plenty of packages which are versioned independently.
 
-## Directory Structure
+Here's the breakdown of the repo:
 
-_Coming soon._
+* Fluid Framework Client Minirepo ([lerna.json](./lerna.json))
+  * [Packages](./packages)
+  * [Example Components](./components/examples)
+  * [Experimental Components](./components/experimental)
+  * [Example host](./examples/hosts/iframe-host)
+* Reference Fluid Ordering Service ("Routerlicious") Minirepo ([dir](./server/routerlicious) | [lerna.json](server/routerlicious/lerna.json))
+  * [Packages](./server/routerlicious/packages)
+* Common Packages
+  * [Common Definitions](./common/lib/common-definitions)
+  * [Common Utils](./common/lib/common-utils)
+* Auxiliary Microservices supporting Routerlicious
+  * [Server dir](./server) (excluding [Routerlicious](./server/routerlicious) itself)
+* Internal/Misc Packages
+  * [Build Common](./common/build/build-common)
+  * [ESlint Config](./common/build/eslint-config-fluid)
+  * Other Example Hosts
+    * [Electron Host](./examples/hosts/electron-host)
+    * [Literate](./examples/hosts/literate)
+  * [Docs](./docs)
+  * [Tools](./tools)
 
 ## Building
 
@@ -67,8 +94,6 @@ npm run build:fast
 
 ## Testing
 
-### Running the tests
-
 You can run the tests from root to run all tests (via lerna), or you can run a scoped set of tests by running the command from the directory you're interested in.
 
 > Note: Some of the tests depend on test collateral that lives in a submodule here: <https://github.com/microsoft/FluidFrameworkTestData>.  You may choose to fetch that collateral into your local repository, which is required to run all the tests - otherwise some will be skipped. First install git LFS from <https://git-lfs.github.com/>. Then, from the repo root:
@@ -80,19 +105,19 @@ You can run the tests from root to run all tests (via lerna), or you can run a s
 >  ```
 >
 
-#### Run the tests
+### Run the tests
 
 ```bash
 npm run test
 ```
 
-#### Include code coverage
+### Include code coverage
 
 ```bash
 npm run test:coverage
 ```
 
-#### Mimic the official CI build
+### Mimic the official CI build
 
 _Note: The official build uses npm run test:full, which doesn’t work on windows._
 
@@ -101,11 +126,11 @@ npm run test:coverage
 npm run test:copyresults
 ```
 
-#### Run tests from within VS Code
+### Run tests from within VS Code
 
 We've checked in [VS Code configuration](https://github.com/microsoft/FluidFramework/blob/master/.vscode/launch.json) enabling F5 from a `spec.ts` file to run those tests, if you set the debug configuration to "Debug Current Test".
 
-## Try it out locally
+## Run it locally
 
 ### Single browser window, two panes
 

common/build/eslint-config-fluid/README.md

@@ -0,0 +1,3 @@
+# @microsoft/eslint-config-fluid
+
+A shared ESLint config used by all the Fluid Framework packages

common/lib/common-definitions/README.md

@@ -1,3 +1,3 @@
-# Fluid Common Definitions
+# @microsoft/fluid-common-definitions
 
-Common interfaces and definitions used in Fluid Framework
+Common interfaces and definitions used in Fluid Framework

common/lib/common-utils/README.md

@@ -1,2 +1,3 @@
-This package contains code for common utilities used by Fluid Framework
+# @microsoft/fluid-common-utils
 
+Common utilities used by Fluid Framework

components/examples/README.md

@@ -0,0 +1,3 @@
+# Example Components
+
+_Coming soon..._

components/experimental/README.md

@@ -0,0 +1,3 @@
+# Experimental Components
+
+_Coming soon..._

examples/hosts/electron-host/README.md

@@ -0,0 +1,3 @@
+# @prague/electron-host
+
+_Coming soon..._

examples/hosts/iframe-host/README.md

@@ -0,0 +1,3 @@
+# @fluid-example/iframe-host
+
+_Coming soon..._

examples/hosts/literate/README.md

@@ -16,7 +16,7 @@ of code.
 ## Build steps
 
 The first (and hardest) step to get up and running is to authenticate against the Fluid private npm feed. To do so
-navigate to https://offnet.visualstudio.com/officenet/_packaging?feed=prague&_a=feed, click the "Connect to feed" link,
+navigate to <https://offnet.visualstudio.com/officenet/_packaging?feed=prague&_a=feed>, click the "Connect to feed" link,
 choose "npm" and then follow the instructions.
 
 Once you've done that getting up and running is simple.
@@ -26,11 +26,11 @@ npm install
 npm start
 ```
 
-Then navigate to http://localhost:8080. This will redirect you to http://localhost:8080/example but you can change
+Then navigate to <http://localhost:8080.> This will redirect you to <http://localhost:8080/example> but you can change
 'example' to any string you'd like and a new document will be created under that name. By default a new Flow View
 will be created but by specifying the chaincode query parameter any of the packages on
-https://packages.wu2.prague.office-int.com can be loaded - i.e.
-http://localhost:8080/new-document?chaincode=@chaincode/tourofheroes@0.0.5918.
+<https://packages.wu2.prague.office-int.com> can be loaded - i.e.
+<http://localhost:8080/new-document?chaincode=@chaincode/tourofheroes@0.0.5918.>
 
 ## The Code
 

packages/README.md

@@ -0,0 +1,23 @@
+# Fluid Framework Client Core Packages
+
+_Details coming soon..._
+
+[agents](./agents) ...
+
+[drivers](./drivers) ...
+
+[framework](./framework) ...
+
+[hosts](./hosts) ...
+
+[loader](./loader) ...
+
+[runtime](./runtime) ...
+
+[server](./server) ...
+
+[test](./test) ...
+
+[tools](./tools) ...
+
+[utils](./utils) ...

server/README.md

@@ -8,6 +8,8 @@ This directory contains our reference server implementation. [Routerlicious](./r
 
 [Charts](./charts) Kubernetes charts for the micro-services
 
+[Gateway](./gateway) Internal landing page for Fluid, hosts Waterpark
+
 [Gitrest](./gitrest) provides a REST API to a GitHub repository. It's API is based off of GitHub's REST APIs.
 
 [Gitssh](./gitssh) is a git ssh server client container.
@@ -20,7 +22,7 @@ This directory contains our reference server implementation. [Routerlicious](./r
 
 [Routerlicious](./routerlicious) composed reference server implementation
 
-[Service](./service) Experimental routerlicious with faster throughput
+[Tinylicious](./tinylicious) Light-weight monolithic server implementation
 
 ## Build Status
 

server/auspkn/README.md

@@ -2,7 +2,7 @@
 
 # Auspkn
 
-Provides REST API access to npm package contents
+Provides REST API access to npm package contents, targeting the internal Azure DevOps (VSTS) feed endpoint today.
 
 ## NPM Repositories
 
@@ -10,4 +10,4 @@ Provides REST API access to npm package contents
 
 To update the config.json to target a repository stored in VSTS follow the usual steps to configure access to
 a repository. But rather than using the base 64 encoded personal access token as the password just include
-the original personal access token directly.
+the original personal access token directly.

server/headless-agent/README.md

@@ -3,7 +3,7 @@
 To begin you'll need to connect to the Fluid private npm repository. Instructions can be found [here](../routerlicious/README.md#authorizing-to-private-npm-feed)
 
 # Headless Agent
-Loads Fluid components on a headless chromium browser.
+Loads Fluid components on a headless chromium browser, as opposed to the Node.js runtime.
 
 To build
 ```

tools/README.md

@@ -0,0 +1,23 @@
+# Fluid Framework Tools Dir
+
+_Details coming soon..._
+
+[build-server-resources](./build-server-resources) ...
+
+[fluid-build-tools](./fluid-build-tools) ...
+
+[fluid-metrics](./fluid-metrics) ...
+
+[fluidpreview-intercept](./fluidpreview-intercept) ...
+
+[generator-fluid](./generator-fluid) Yo generator for creating a new Fluid Component
+
+[getkeys](./getkeys) ...
+
+[headless-chrome](./headless-chrome) ...
+
+[logger](./logger) ...
+
+[repo-policy-check](./repo-policy-check) ...
+
+[search-content-extractor](./search-content-extractor) ...