From ebb363e938a279cf866cb93d28e31aaf0791ea19 Mon Sep 17 00:00:00 2001
From: Lisanna Dettwyler <lisanna.dettwyler@intel.com>
Date: Mon, 23 Mar 2020 15:03:56 -0700
Subject: [PATCH] Documentation updates

---
 README.md | 61 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 46 insertions(+), 15 deletions(-)

diff --git a/README.md b/README.md
index 433ccdd5..169a02a4 100644
--- a/README.md
+++ b/README.md
@@ -1,24 +1,42 @@
-# Contents
-This repo contains the following:
-- oneAPI Level Zero Specification API C/C++ header files.
-  https://spec.oneapi.com/versions/latest/elements/l0/source/index.html
+# oneAPI Level Zero
 
-- oneAPI Level Zero loader
+This repository contains the following components of oneAPI:
+
+- Copies of the Level Zero Specification API C/C++ header files
+- Level Zero Loader
+- Level Zero Validation Layer
+
+This project is part of the larger [oneAPI](https://www.oneapi.com/) project.
+See **Contributing** below for details about submitting issues and pull
+requests.
+
+oneAPI Specification: https://spec.oneapi.com/versions/latest/introduction.html
+
+oneAPI Level Zero Specification: https://spec.oneapi.com/versions/latest/oneL0/index.html
+
+The versions of the Level Zero API are listed in the file
+[ze_driver.h](./include/core/ze_driver.h) in the `ze_api_version_t` enum.
+
+# Building and Installing
 
-# Building
 Project is defined using [CMake](https://cmake.org/).
 
-**Linux**:
-Executable and binaries will be in **build/bin**
-~~~~
+## Linux
+
+### General
+
+```
 mkdir build
 cd build
-cmake {path_to_source_dir}
-make [package]
-~~~~
+cmake ..
+cmake --build . --config Release
+cmake --build . --config Release --target package
+cmake --build . --config Release --target install
+```
+
+### Ubuntu with Docker
 
-**Linux with Docker**:
-~~~bash
+```bash
 mkdir build
 mkdir -p .ccache
 
@@ -31,6 +49,7 @@ docker run \
   $(docker build -q \
       --build-arg UID=$(id -u) \
       --build-arg GID=$(id -g) \
+      --build-arg IMAGE_VERSION=eoan \
       - < docker/build-ubuntu.Dockerfile) \
   cmake \
     -G Ninja \
@@ -48,6 +67,18 @@ docker run \
   $(docker build -q \
       --build-arg UID=$(id -u) \
       --build-arg GID=$(id -g) \
+      --build-arg IMAGE_VERSION=eoan \
       - < docker/build-ubuntu.Dockerfile) \
   cmake --build . --config Release
-~~~
+```
+
+# Contributing
+
+We encourage anyone who wants to contribute to submit
+[Issues](https://github.com/oneapi-src/level-zero/issues) and
+[Pull Requests](https://github.com/oneapi-src/level-zero/pulls). We will help
+review these for proper alignment with the
+[Level Zero Specification](https://spec.oneapi.com/versions/latest/oneL0/index.html).
+
+Specific coding conventions and standards guidelines are a work-in-progress, and
+we will post them here soon.