First pass of docs update

CONTRIBUTING.md

@@ -1,121 +0,0 @@
-# Contributors Guide
-
-Lighthouse is an open-source Ethereum 2.0 client. We we're community driven and
-welcome all contribution. We aim to provide a constructive, respectful and fun
-environment for collaboration.
-
-We are active contributors to the [Ethereum 2.0 specification](https://github.com/ethereum/eth2.0-specs) and attend all [Eth
-2.0 implementers calls](https://github.com/ethereum/eth2.0-pm).
-
-This guide is geared towards beginners. If you're an open-source veteran feel
-free to just skim this document and get straight into crushing issues.
-
-## Why Contribute
-
-There are many reasons you might contribute to Lighthouse. For example, you may
-wish to:
-
-- contribute to the Ethereum ecosystem.
-- establish yourself as a layer-1 Ethereum developer.
-- work in the amazing Rust programming language.
-- learn how to participate in open-source projects.
-- expand your software development skills.
-- flex your skills in a public forum to expand your career
-  opportunities (or simply for the fun of it).
-- grow your network by working with core Ethereum developers.
-
-## How to Contribute
-
-Regardless of the reason, the process to begin contributing is very much the
-same. We operate like a typical open-source project operating on GitHub: the
-repository [Issues](https://github.com/sigp/lighthouse/issues) is where we
-track what needs to be done and [Pull
-Requests](https://github.com/sigp/lighthouse/pulls) is where code gets
-reviewed. We use [gitter](https://gitter.im/sigp/lighthouse) to chat
-informally.
-
-### General Work-Flow
-
-We recommend the following work-flow for contributors:
-
-1. **Find an issue** to work on, either because it's interesting or suitable to
-   your skill-set. Use comments to communicate your intentions and ask
-questions.
-2. **Work in a feature branch** of your personal fork
-   (github.com/YOUR_NAME/lighthouse) of the main repository
-   (github.com/sigp/lighthouse).
-3. Once you feel you have addressed the issue, **create a pull-request** to merge
-   your changes in to the main repository.
-4. Wait for the repository maintainers to **review your changes** to ensure the
-   issue is addressed satisfactorily. Optionally, mention your PR on
-[gitter](https://gitter.im/sigp/lighthouse).
-5. If the issue is addressed the repository maintainers will **merge your
-   pull-request** and you'll be an official contributor!
-
-Generally, you find an issue you'd like to work on and announce your intentions
-to start work in a comment on the issue. Then, do your work on a separate
-branch (a "feature branch") in your own fork of the main repository.  Once
-you're happy and you think the issue has been addressed, create a pull request
-into the main repository.
-
-### First-time Set-up
-
-First time contributors can get their git environment up and running with these
-steps:
-
-1. [Create a
-   fork](https://help.github.com/articles/fork-a-repo/#fork-an-example-repository)
-and [clone
-it](https://help.github.com/articles/fork-a-repo/#step-2-create-a-local-clone-of-your-fork)
-to your local machine.
-2. [Add an _"upstream"_
-   branch](https://help.github.com/articles/fork-a-repo/#step-3-configure-git-to-sync-your-fork-with-the-original-spoon-knife-repository)
-that tracks github.com/sigp/lighthouse using `$ git remote add upstream
-https://github.com/sigp/lighthouse.git` (pro-tip: [use SSH](https://help.github.com/articles/connecting-to-github-with-ssh/) instead of HTTPS).
-3. Create a new feature branch with `$ git checkout -b your_feature_name`. The
-   name of your branch isn't critical but it should be short and instructive.
-E.g., if you're fixing a bug with serialization, you could name your branch
-`fix_serialization_bug`.
-4. Commit your changes and push them to your fork with `$ git push origin
-   your_feature_name`.
-5. Go to your fork on github.com and use the web interface to create a pull
-   request into the sigp/lighthouse repo.
-
-From there, the repository maintainers will review the PR and either accept it
-or provide some constructive feedback.
-
-There's great
-[guide](https://akrabat.com/the-beginners-guide-to-contributing-to-a-github-project/)
-by Rob Allen that provides much more detail on each of these steps, if you're
-having trouble. As always, jump on [gitter](https://gitter.im/sigp/lighthouse)
-if you get stuck.
-
-
-## FAQs
-
-### I don't think I have anything to add
-
-There's lots to be done and there's all sorts of tasks. You can do anything
-from correcting typos through to writing core consensus code. If you reach out,
-we'll include you.
-
-### I'm not sure my Rust is good enough
-
-We're open to developers of all levels. If you create a PR and your code
-doesn't meet our standards, we'll help you fix it and we'll share the reasoning
-with you. Contributing to open-source is a great way to learn.
-
-### I'm not sure I know enough about Ethereum 2.0
-
-No problems, there's plenty of tasks that don't require extensive Ethereum
-knowledge. You can learn about Ethereum as you go.
-
-### I'm afraid of making a mistake and looking silly
-
-Don't be. We're all about personal development and constructive feedback. If you
-make a mistake and learn from it, everyone wins.
-
-### I don't like the way you do things
-
-Please, make an issue and explain why. We're open to constructive criticism and
-will happily change our ways.

README.md

@@ -7,7 +7,51 @@ Chain, maintained by Sigma Prime.
 
 The "Serenity" project is also known as "Ethereum 2.0" or "Shasper".
 
-## Lighthouse Client
+## Project Structure
+
+The Lighthouse project is managed across four Github repositories:
+
+- [sigp/lighthouse](https://github.com/sigp/lighthouse) (this repo): The
+	"integration" repository which provides:
+	- Project-wide documentation
+	- A sub-module for each of the following repos.
+	- A landing-page for users and contributors.
+	- A triage point for issues.
+	- In the future, various other integration tests and orchestration suites.
+- [sigp/lighthouse-libs](https://github.com/sigp/lighthouse-libs): Contains
+	Rust crates common to the entire Lighthouse project, including:
+	- Pure specification logic (e.g., state transitions, etc)
+	- SSZ (SimpleSerialize)
+	- BLS Signature libraries
+- [sigp/lighthouse-beacon](https://github.com/sigp/lighthouse-beacon): The
+	beacon node binary, responsible for connection to peers across the
+	network and maintaining a view of the Beacon Chain.
+- [sigp/lighthouse-validator](https://github.com/sigp/lighthouse-validator):
+	The validator client binary, which connects to a beacon node and fulfils
+	the duties of a staked validator (producing and attesting to blocks).
+
+## Contributing
+
+We welcome new contributors and greatly appreciate the efforts from existing
+contributors.
+
+If you'd like to contribute to development on Lighthouse, we'd recommend
+checking for [issues on the lighthouse-libs
+repo](https://github.com/sigp/lighthouse-libs/issues) first, then checking the
+other repositories.
+
+If you don't find anything there, please reach out on the
+[gitter](https://gitter.im/sigp/lighthouse) channel.
+
+Additional resources:
+
+- [ONBOARDING.md](docs/ONBOARDING.md): General on-boarding info,
+	including style-guide.
+- [LIGHTHOUSE.md](docs/LIGHTHOUSE.md): Project goals and ethos.
+- [RUNNING.md](docs/RUNNING.md): Step-by-step on getting the code running.
+- [SERENITY.md](docs/SERENITY.md): Introduction to Ethereum Serenity.
+
+## Project Summary
 
 Lighthouse is an open-source Ethereum Serenity client that is currently under
 development. Designed as a Serenity-only client, Lighthouse will not
@@ -19,15 +63,6 @@ to existing clients, such as
 [Parity-Ethereum](https://github.com/paritytech/parity-ethereum), via RPC to enable
 present-Ethereum functionality.
 
-### Further Reading
-
-- [About Lighthouse](docs/lighthouse.md): Goals, Ideology and Ethos surrounding
-this implementation.
-- [What is Ethereum Serenity](docs/serenity.md): an introduction to Ethereum Serenity.
-
-If you'd like some background on Sigma Prime, please see the [Lighthouse Update
-\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the
-[company website](https://sigmaprime.io).
 
 ### Components
 
@@ -61,7 +96,7 @@ by the team:
   from the Ethereum Foundation to develop *simpleserialize* (SSZ), a
   purpose-built serialization format for sending information across a network.
   Check out the [SSZ
-implementation](https://github.com/sigp/lighthouse/tree/master/beacon_chain/utils/ssz)
+implementation](https://github.com/sigp/lighthouse-libs/tree/master/ssz)
 and this
 [research](https://github.com/sigp/serialization_sandbox/blob/report/report/serialization_report.md)
 on serialization formats for more information.
@@ -79,89 +114,23 @@ In addition to these components we are also working on database schemas, RPC
 frameworks, specification development, database optimizations (e.g.,
 bloom-filters), and tons of other interesting stuff (at least we think so).
 
-### Directory Structure
-
-Here we provide an overview of the directory structure:
-
-- `beacon_chain/`: contains logic derived directly from the specification.
-  E.g., shuffling algorithms, state transition logic and structs, block
-validation, BLS crypto, etc.
-- `lighthouse/`: contains logic specific to this client implementation. E.g.,
-  CLI parsing, RPC end-points, databases, etc.
-
-### Running
-
-**NOTE: The cryptography libraries used in this implementation are
-experimental. As such all cryptography is assumed to be insecure.**
-
-This code-base is still very much under-development and does not provide any
-user-facing functionality. For developers and researchers, there are several
-tests and benchmarks which may be of interest.
-
-A few basic steps are needed to get set up:
-
-   1. Install [rustup](https://rustup.rs/).  It's a toolchain manager for Rust (Linux | macos | Windows). For installation run the below command in your terminal `$ curl https://sh.rustup.rs -sSf | sh`
-   2. (Linux & MacOS) To configure your current shell run: `$ source $HOME/.cargo/env`
-   3. Use the command `rustup show` to get information about the Rust installation. You should see that the
-   active toolchain is the stable version.
-   4. Run `rustc --version` to check the installation and version of rust.
-      - Updates can be performed using` rustup update` .
-   5. Install build dependencies (Arch packages are listed here, your distribution will likely be similar):
-	  - `clang`: required by RocksDB.
-	  - `protobuf`: required for protobuf serialization (gRPC).
-   6. Navigate to the working directory.
-   7. Run the test by using command `cargo test --all`. By running, it will pass all the required test cases.
-        If you are doing it for the first time, then you can grab a coffee in the meantime. Usually, it takes time
-        to build, compile and pass all test cases. If there is no error then it means everything is working properly
-        and it's time to get your hands dirty.
-        In case, if there is an error, then please raise the [issue](https://github.com/sigp/lighthouse/issues).
-        We will help you.
-   8. As an alternative to, or instead of the above step, you may also run benchmarks by using
-        the command `cargo bench --all`
-
-##### Note:
-Lighthouse presently runs on Rust `stable`, however, benchmarks currently require the
-`nightly` version.
-
-##### Note for Windows users:
-Perl may also be required to build lighthouse. You can install [Strawberry Perl](http://strawberryperl.com/),
-or alternatively use a choco install command `choco install strawberryperl`.
-
-Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues compiling in Windows. You can specify
-a known working version by editing version in protos/Cargo.toml's "build-dependencies" section to
-`protoc-grpcio = "<=0.3.0"`.
-
-### Contributing
-
-**Lighthouse welcomes contributors with open-arms.**
-
-If you would like to learn more about Ethereum Serenity and/or
-[Rust](https://www.rust-lang.org/), we are more than happy to on-board you
-and assign you some tasks. We aim to be as accepting and understanding as
-possible; we are more than happy to up-skill contributors in exchange for their
-assistance with the project.
-
-Alternatively, if you are an ETH/Rust veteran, we'd love your input.  We're
-always looking for the best way to implement things and welcome all
-respectful criticisms.
-
-If you are looking to contribute, please head to our
-[onboarding documentation](https://github.com/sigp/lighthouse/blob/master/docs/onboarding.md).
-
-If you'd like to contribute, try having a look through the [open
-issues](https://github.com/sigp/lighthouse/issues) (tip: look for the [good
-first
-issue](https://github.com/sigp/lighthouse/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)
-tag) and ping us on the [gitter](https://gitter.im/sigp/lighthouse) channel. We need
-your support!
 
 ## Contact
 
 The best place for discussion is the [sigp/lighthouse gitter](https://gitter.im/sigp/lighthouse).
 Ping @paulhauner or @AgeManning to get the quickest response.
 
+If you'd like some background on Sigma Prime, please see the [Lighthouse Update
+\#00](https://lighthouse.sigmaprime.io/update-00.html) blog post or the
+[company website](https://sigmaprime.io).
+
 # Donations
 
-If you support the cause, we could certainly use donations to help fund development:
+We accept donations at the following Ethereum address. All donations go towards
+funding development of Ethereum 2.0.
 
-`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b`
+[`0x25c4a76E7d118705e7Ea2e9b7d8C59930d8aCD3b`](https://etherscan.io/address/0x25c4a76e7d118705e7ea2e9b7d8c59930d8acd3b)
+
+Alternatively, you can contribute via [Gitcoin Grant](https://gitcoin.co/grants/25/lighthouse-ethereum-20-client).
+
+We appreciate all contributions to the project.

docs/README.md

@@ -0,0 +1,10 @@
+# Lighthouse Documentation
+
+Table of Contents:
+
+
+- [ONBOARDING.md](ONBOARDING.md): General on-boarding info,
+	including style-guide.
+- [LIGHTHOUSE.md](LIGHTHOUSE.md): Project goals and ethos.
+- [RUNNING.md](RUNNING.md): Step-by-step on getting the code running.
+- [SERENITY.md](SERENITY.md): Introduction to Ethereum Serenity.

docs/RUNNING.md

@@ -0,0 +1,53 @@
+# Running Lighthouse Code
+
+These documents provide a guide for running code in the following repositories:
+
+- [lighthouse-libs](https://github.com/sigp/lighthouse-libs)
+- [lighthouse-beacon](https://github.com/sigp/lighthouse-beacon
+- [lighthouse-validator](https://github.com/sigp/lighthouse-validator
+
+**NOTE: The cryptography libraries used in this implementation are
+experimental. As such all cryptography is assumed to be insecure.**
+
+This code-base is still very much under-development and does not provide any
+user-facing functionality. For developers and researchers, there are several
+tests and benchmarks which may be of interest.
+
+A few basic steps are needed to get set up:
+
+   1. Install [rustup](https://rustup.rs/).  It's a toolchain manager for Rust
+	  (Linux | macos | Windows). For installation run the below command in your
+	  terminal `$ curl https://sh.rustup.rs -sSf | sh`
+   2. (Linux & MacOS) To configure your current shell run: `$ source
+	  $HOME/.cargo/env`
+   3. Use the command `rustup show` to get information about the Rust
+	  installation. You should see that the active toolchain is the stable
+	  version.
+   4. Run `rustc --version` to check the installation and version of rust.
+	  - Updates can be performed using` rustup update` .
+   5. Install build dependencies (Arch packages are listed here, your
+   distribution will likely be similar):
+	  - `clang`: required by RocksDB.  `protobuf`: required for protobuf
+	  - serialization (gRPC).
+   6. Navigate to the working directory.
+   7. Run the test by using command `cargo test --all`. By running, it will
+   pass all the required test cases.  If you are doing it for the first time,
+   then you can grab a coffee in the meantime. Usually, it takes time to build,
+   compile and pass all test cases. If there is no error then it means
+   everything is working properly and it's time to get your hands dirty.  In
+   case, if there is an error, then please raise the
+   [issue](https://github.com/sigp/lighthouse/issues).  We will help you.
+   8. As an alternative to, or instead of the above step, you may also run
+   benchmarks by using the command `cargo bench --all`. (Note: not all
+   repositories have benchmarking).
+
+##### Note: Lighthouse presently runs on Rust `stable`.
+
+##### Note for Windows users: Perl may also be required to build lighthouse.
+You can install [Strawberry Perl](http://strawberryperl.com/), or alternatively
+use a choco install command `choco install strawberryperl`.
+
+Additionally, the dependency `protoc-grpcio v0.3.1` is reported to have issues
+compiling in Windows. You can specify a known working version by editing
+version in protos/Cargo.toml's "build-dependencies" section to `protoc-grpcio =
+"<=0.3.0"`.