Minor fixes and improvements.

docs/README.md

@@ -1,15 +1,15 @@
 GraalVM is a project based in Oracle Labs developing a new JIT Compiler and Polyglot Runtime for the JVM.
 Further details can be found on the [OTN site](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/index.html).
 
-[Graal SDK](../sdk) is the Graal Standard Development Kit that contains long term supported APIs.
+* [Graal SDK](../sdk) contains long term supported APIs of GraalVM.
 
-[Graal](../compiler) is a dynamic compiler written in Java that integrates with the HotSpot JVM.
+* [Graal](../compiler) is a dynamic compiler written in Java that integrates with the HotSpot JVM.
 
-[Truffle](../truffle) is a framework for implementing languages and instrumentations that use Graal as a dynamic compiler.
+* [Truffle](../truffle) is a framework for implementing languages and instruments that use Graal as a dynamic compiler.
 
-[Tools](../tools) contains a set of tools for Truffle guest langauges implemeted using the instrumentation framework.
+* [Tools](../tools) contains a set of tools for Truffle guest languages implemented using the instrumentation framework.
 
-[Substrate VM](../substratevm) is a framework that allows ahead-of-time (AOT) compilation of Java applications under closed-world assumption into executable images or shared objects.
+* [Substrate VM](../substratevm) is a framework that allows ahead-of-time (AOT) compilation of Java applications under closed-world assumption into executable images or shared objects.
 
 ## License
 

sdk/README.md

@@ -2,16 +2,15 @@
 
 The Graal SDK is a collection of APIs for the components of GraalVM.
 
-
 * The [`org.graalvm.polyglot`](http://www.graalvm.org/sdk/javadoc/org/graalvm/polyglot/package-summary.html) module contains APIs to embed Graal languages in Java host applications.
 * The [`org.graalvm.collections`](http://www.graalvm.org/sdk/javadoc/org/graalvm/collections/package-summary.html) module contains memory efficient common collection data structures used across Graal projects.
 * The [`org.graalvm.options`](http://www.graalvm.org/sdk/javadoc/org/graalvm/options/package-summary.html) module contains reusable classes for options.
 
 ## Getting Started
 
-1. Download GraalVM from Oracle Technology Network.
+1. Download GraalVM from [Oracle Technology Network](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/).
 2. Use any of the Java executables in `./bin` or import GraalVM as JDK in your favorite IDE.
-3. Use Graal-SDK, it is put on the classpath for you automatically. 
+3. Use Graal-SDK, the jar is put on the class path for you automatically. 
 
 The Graal-SDK bits are also uploaded to Maven central.
 You can use it from your `pom.xml` file as:
@@ -26,7 +25,7 @@ You can use it from your `pom.xml` file as:
   </dependencies>
 ```
 
-Please note that Graal SDK still requires GraalVM to run.
+Please note that Graal SDK requires GraalVM to run.
 
 ## Tutorials
 

truffle/README.md

@@ -3,7 +3,7 @@
 ## Introduction
 
 Truffle is an Open Source library for building programming language implementations as interpreters for self-modifying Abstract Syntax Trees.
-Together with the Open Source [Graal compiler][https://github.com/graalvm/graal/tree/master/compiler], Truffle represents a significant step 
+Together with the Open Source [Graal compiler](../compiler), Truffle represents a significant step 
 forward in programming language implementation technology in the current era of dynamic languages.
 
 A growing  body of shared implementation code and services
@@ -12,15 +12,13 @@ performance that matches or exceeds the competition.  The value of the platform
 increased by support for low-overhead language interoperation, as well as a general instrumentation
 framework that supports multi-language debugging and other external developer tools.
 
-Find a comprehensive list of all known Truffle languages [here](./docs/Languages.md).
-
 Truffle is developed and maintained by Oracle Labs and the Institute for System
 Software of the Johannes Kepler University Linz.
 
 ## Using Truffle
 
 Information on how to get starting building your language can be found in the Truffle language implementation [tutorial](./docs/LanguageTutorial.md).
-Reference API documentation is available as part of the [Truffle javadoc] (http://graalvm.org/truffle/javadoc/).
+The reference API documentation is available as part of the [Truffle javadoc](http://graalvm.org/truffle/javadoc/).
 Truffle comes prebuilt with Graal and several language implementations as as part of [GraalVM](http://www.oracle.com/technetwork/oracle-labs/program-languages/overview/).
 
 The Truffle bits are uploaded to Maven central. You can use them from your
@@ -43,10 +41,12 @@ The Truffle bits are uploaded to Maven central. You can use them from your
 If you want to implement your own Truffle guest language, a good way to start is to fork the [SimpleLanguage](https://github.com/graalvm/simplelanguage) project and start hacking.
 SimpleLanguage is well documented and designed to demonstrate most of the Truffle features.
 
-Important links:
+*To learn more:*
+
 * Start with a new subclass of [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) for your own language implementation.
 * Start with a new subclass of [TruffleInstrument](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/instrumentation/TruffleInstrument.html) for your own instrumentation/tool.
 * Fork [SimpleLanguage](https://github.com/graalvm/simplelanguage), a toy language that demonstrates how to use most Truffle features.
+* Get inspired by looking at code of one of existing open source Truffle language implementations and experiments [here](./docs/Languages.md).
 * Embed Truffle languages in Java host applications using the [Polyglot API](../../sdk/docs/PolyglotEmbedding.md).
 * Read The Graal/Truffle [publications](../../docs/Publications.md)
 * Verify that your language is a valid polyglot citizen using the [Polyglot TCK](./docs/TCK.md).
@@ -55,7 +55,6 @@ Important links:
 
 The Truffle API is evolved in a backwards compatible manner from one version to the next.
 When API is deprecated, then it will stay deprecated for at least two Truffle releases and a minimum of one month before it will be removed.
-The [Polyglot API](../../sdk/docs/PolyglotEmbedding.md) is a long-term stable API to embed languages in Java applications.
 
 As a best practice it is recommended to upgrade Truffle only one version at a time.
 This way you can increment the version, fix deprecation warnings to continue with the next version.

truffle/docs/LanguageTutorial.md

@@ -4,15 +4,14 @@ For an excellent, in-depth presentation on how to implement your language with T
 please have a look at a [three hour walkthrough](https://youtu.be/FJY96_6Y3a4) presented at a recent
 Conference on Programming Language Design and Implementation [PLDI 2016](http://conf.researchr.org/home/pldi-2016).
 
-
 <a href="http://www.youtube.com/watch?feature=player_embedded&v=FJY96_6Y3a4" target="_blank">
 <img src="http://img.youtube.com/vi/FJY96_6Y3a4/0.jpg" alt="Youtube Video Player" width="854" height="480" border="10" />
 </a>
 
 [Download Slides](https://lafo.ssw.uni-linz.ac.at/pub/papers/2016_PLDI_Truffle.pdf)
 
 Next Steps:
-* Start to subclass [TruffleLanguage]() for your own language implementation.
+* Start to subclass [TruffleLanguage](http://www.graalvm.org/truffle/javadoc/com/oracle/truffle/api/TruffleLanguage.html) for your own language implementation.
 * Fork [SimpleLanguage](https://github.com/graalvm/simplelanguage), a toy language that demonstrates how to use many Truffle features.
 * Embed Truffle languages in Java host applications using the [Polyglot API](../../sdk/docs/PolyglotEmbedding.md).
 * Read The Graal/Truffle [publications](../../docs/Publications.md)

truffle/docs/Languages.md

@@ -1,5 +1,3 @@
-# Known Truffle Language Implementations
-
 This page is intended to keep track of the growing number of Truffle language implementations and experiments.
 
 ## Language implementations
@@ -31,6 +29,6 @@ This page is intended to keep track of the growing number of Truffle language im
 * [Reactive Ruby](https://github.com/guidosalva/ReactiveRubyTruffle), TruffleRuby meets Reactive Programming.
 * [PorcE](https://github.com/orc-lang/orc/tree/master/PorcE), an Orc language implementation.
 * [shen-truffle](https://github.com/ragnard/shen-truffle), a port of the Shen programming language.
-* [bf](https://github.com/chumer/bf/), a Brainfuck programming language implementation.
+* [bf](https://github.com/chumer/bf/), an experimental Brainfuck programming language implementation.
 
 Feel free to submit a [pull request](https://help.github.com/articles/using-pull-requests/) to add/remove from this list.