Instruct to use the Eclipse installer instead of extracting the package, describe first launch and plugin installation.

1 files changed, 29 insertions, 6 deletions

diff --git a/Eclipse.md b/Eclipse.md
index 26e69fac1..42a0cc275 100644
--- a/Eclipse.md
+++ b/Eclipse.md
@@ -9,13 +9,17 @@ Using an IDE such as Eclipse provides many advantages over a plain text editor,
 * static code analysis
 * many other tools such as debugging, code formatting, showing call hierarchies etc.
 
-The goal of the is page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
+The purpose of the is page is to document how to set-up Eclipse for developing AVR software, and working on the QMK code base.
 
 Note that this set-up has been tested on Ubuntu 16.04 only for the moment.
 
 # Prerequisites
+## Build environment
 Before starting, you must have followed the [Getting Started](../#getting-started) section corresponding to your system. In particular, you must have been able to build the firmware with [the `make` command](../#the-make-command).
 
+## Java
+Eclipse is a Java application, so you will need to install Java 8 or more recent to be able to run it. You may choose between the JRE or the JDK, the latter being useful if you intend to do Java development.
+
 # Install Eclipse and its plugins
 Eclipse comes in [several flavours](http://www.eclipse.org/downloads/eclipse-packages/) depending on the target usage that you will have. There is no package comprising the AVR stack, so we will need to start from Eclipse CDT (C/C++ Development Tooling) and install the necessary plugins.
 
@@ -24,13 +28,32 @@ If you already have Eclipse CDT on your system, you can skip this step. However
 
 If you have another Eclipse package installed, it is normally possible to [install the CDT plugin over it](https://eclipse.org/cdt/downloads.php). However it is probably better to reinstall it from scratch to keep it light and avoid the clutter of tools that you don't need for the projects you will be working on.
 
-Installation is very simple:
-* [Download Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/eclipse-packages/) ([direct link to current version](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)) from the official Eclipse website
-* Extract the package to the location of your choice (this creates an `eclipse` folder)
-* (optional) Rename the extracted `eclipse` folder to something more specific like `eclipse-cpp-neon-x64` (to avoid conflicts if you install several packages of Eclipse)
+Installation is very simple: follow the [5 Steps to Install Eclipse](https://eclipse.org/downloads/eclipse-packages/?show_instructions=TRUE), and choose **Eclipse IDE for C/C++ Developers** at Step 3.
+
+Alternatively, you can also directly [download Eclipse IDE for C/C++ Developers](http://www.eclipse.org/downloads/eclipse-packages/) ([direct link to current version](http://www.eclipse.org/downloads/packages/eclipse-ide-cc-developers/neonr)) and extract the package to the location of your choice (this creates an `eclipse` folder).
+
+## First Launch
+When installation is complete, click the <kbd>Launch</kbd> button. (If you extracted the package manually, open the Eclipse installation folder and double-click the `eclipse` executable)
+
+When you are prompted with the Workspace Selector, select a directory that will hold Eclipse metadata and usually your projects. **Do not select the `qmk_firmware` directory**, this will be the project directory. Select the parent folder instead, or another (preferably empty) folder of your choice (the default is fine if you do not use it yet).
+
+Once started, click the <kbd>Workbench</kbd> button at the top right to switch to the workbench view (there is a also checkbox at the bottom to skip the welcome screen at startup).
 
 ## Install the necessary plugins
-(todo)
+Note: you do not need to restart Eclipse after installing each plugin. Simply restart once all plugins are installed.
+
+### [The AVR plugin](http://avr-eclipse.sourceforge.net/)
+This is the most important plugin as it will allow Eclipse to _understand_ AVR C code. Follow [the instructions for using the update site](http://avr-eclipse.sourceforge.net/wiki/index.php/Plugin_Download#Update_Site), and agree with the security warning for unsigned content.
+
+### [ANSI Escape in Console](https://marketplace.eclipse.org/content/ansi-escape-console)
+This plugin is necessary to properly display the colored build output generated by the QMK makefile.
+
+1. Open <kbd><kbd>Help</kbd> > <kbd>Eclipse Marketplace…</kbd></kbd>
+2. Search for _ANSI Escape in Console_
+3. Click the <samp>Install</samp> button of the plugin
+4. Follow the instructions and agree again with the security warning for unsigned content.
+
+Once both plugins are installed, restart Eclipse as prompted.
 
 # Configure Eclipse for QMK
 (todo)
\ No newline at end of file