updating build instructions

16 files changed, 235 insertions, 400 deletions

diff --git a/android/BuildInstructions.md b/android/BuildInstructions.md
index 538339e98f9..32b66d52e8b 100644
--- a/android/BuildInstructions.md
+++ b/android/BuildInstructions.md
@@ -17,12 +17,12 @@ include pre-compiled JAR files.
 Building any Ice application for Android requires Android Studio and the Android
 SDK build tools. We tested with the following components:
 
-- Android Studio 1.2.1
-- Android SDK Build-tools 21.1.1
+- Android Studio 2.3
+- Android SDK Build-tools 25
 
-Ice requires at minimum API level 17:
+Ice requires at minimum API level 21:
 
-- Android 4.2.2 (API17)
+- Android 5 (API21)
 
 If you want to target a later version of the Android API level for the test
 suite, edit `gradle.properties` and change the following variables:
diff --git a/cpp/BuildInstructions.md b/cpp/BuildInstructions.md
index 0ee0efc70de..fd0c58397ee 100644
--- a/cpp/BuildInstructions.md
+++ b/cpp/BuildInstructions.md
@@ -1,6 +1,5 @@
 # Building Ice for C++
 
-- [Building Ice for C++ on AIX.](BuildInstructionsAIX.md)
-- [Building Ice for C++ on Linux.](BuildInstructionsLinux.md)
-- [Building Ice for C++ on Linux.](BuildInstructionsOSX.md)
-- [Building Ice for C++ on Windows.](BuildInstructionsWindows.md)
\ No newline at end of file
+- [Building Ice for C++ on Linux](BuildInstructionsLinux.md)
+- [Building Ice for C++ on macOS](BuildInstructionsMacOS.md)
+- [Building Ice for C++ on Windows](BuildInstructionsWindows.md)
diff --git a/cpp/BuildInstructionsAIX.md b/cpp/BuildInstructionsAIX.md
deleted file mode 100644
index 59dcb261e14..00000000000
--- a/cpp/BuildInstructionsAIX.md
+++ /dev/null
@@ -1,164 +0,0 @@
-# Building Ice for C++ on AIX
-
-This document provides step-by-step instructions for building Ice for C++
-from sources on AIX.
-
-## Unsupported Platform
-
-AIX is currently an unsupported platform. Only minimal testing was performed
-on AIX, and there is no guarantee future releases of Ice will build or run
-on this platform.
-
-## Recommended Operating System and C++ Compiler
-
- - AIX 6.1, AIX 7.1
- - IBM XL C/C++ 12.1 with latest Fix Pack
- - 32 bit or 64 bit
-
-## Build Pre-Requisites
-
-Before building Ice, you need to install or build a number of third-party
-packages that Ice depends on, and install some build tools.
-
-### Third-Party Packages
-
-Ice depends on several open-source packages: bzip2 1.0, expat 2.x, LMDB 0.9.x, 
-mcpp 2.7.2 (+patches) and OpenSSL.
-
-OpenSSL is a system package on AIX. RPM packages for bzip2 and expat are
-available in the [AIX Toolbox for Linux Applications][1]. You can install
-them as follows:
-
-```
-# As root
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/bzip2/bzip2-1.0.5-3.aix5.3.ppc.rpm
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/expat/expat-2.0.1-2.aix5.3.ppc.rpm
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/expat/expat-devel-2.0.1-2.aix5.3.ppc.rpm
-
-```
-
-LMDB and mcpp must be built from sources, as described below. 
-
-### Build Tools
-
-You need GNU make (gmake) to build Ice:
-```
-# As root
-rpm -i ftp://public.dhe.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/make/make-4.1-2.aix6.1.ppc.rpm
-```
-
-The preferred way to retrieve the Ice and mcpp source distributions is with
-git. A RPM for git is available from [bullfreeware.com][2].
-
-### Building mcpp from Sources
-
-If building 64-bit binaries, set `OBJECT_MODE` to 64:
-```
-export OBJECT_MODE=64
-```
-Otherwise, leave `OBJECT_MODE` unset.
-
-Then clone the zeroc-ice/mcpp repository and build with gmake:
-```
-git clone https://github.com/zeroc-ice/mcpp.git
-cd mcpp
-gmake
-```
-
-This build creates a static library, `lib/libmcpp.a`. `libmcpp.a` is used
-only when building Ice from sources, and does not need to be installed.
-
-### Building LMDB from Sources
-
-TBD
-
-## Building Ice
-
-### Clone zeroc-ice/ice
-
-```
-git clone https://github.com/zeroc-ice/ice.git
-cd ice
-```
-
-### Configure
-
-Edit `config/Make.rules` to establish your build configuration. The comments
-in the file provide more information.
-
-Make sure to set `LMDB_HOME` to your LMDB installation directory and 
-`MCPP_HOME` to your mcpp build directory (for example `$(HOME)/builds/mcpp`).
-
-### Build
-
-Use the gmake `-j` option to speed up the build:
-
-```
-cd cpp
-gmake -j8
-```
-
-This builds the Ice core libraries, services, and tests.
-
-### Build configurations and platforms
-
-The C++ source tree supports multiple build configurations and platforms. To
-see the supported configurations and platforms:
-
-    gmake print V=supported-configs
-    gmake print V=supported-platforms
-
-To build all the supported configurations and platforms:
-
-    gmake CONFIGS=all PLATFORMS=all
-
-### C++11 mapping
-
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
-
-To build the new C++11 mapping, use build configurations which are prefixed with
-`cpp11`, for example:
-
-    gmake CONFIGS=cpp11-shared
-
-### Install
-
-Simply run `gmake install`. This will install Ice in the directory specified by
-the `<prefix>` variable in `config/Make.rules`.
-
-By default, all Ice binaries embed the library path `prefix/lib:/usr/lib`.
-
-After installation, make sure that the `prefix/bin` directory is in your `PATH`.
-
-### Run the Test Suite (Optional)
-
-Python is required to run the test suite. You can install Python as follows:
-```
-# As root
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-2.7.10-1.aix6.1.ppc.rpm
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-tools-2.7.10-1.aix6.1.ppc.rpm
-rpm -i ftp://ftp.software.ibm.com/aix/freeSoftware/aixtoolbox/RPMS/ppc/python/python-devel-2.7.10-1.aix6.1.ppc.rpm
-```
-
-Additionally, the Glacier2 tests require the Python module `passlib`, available
-from the Python Package Index:
-```
-# As root
-wget https://bootstrap.pypa.io/get-pip.py
-python get-pip.py
-export PATH=/opt/freeware/bin:$PATH
-pip install passlib
-```
-
-Then run the test suite with:
-```
-python allTests.py
-```
-
-If everything worked out, you should see lots of `ok` messages. In case of a
-failure, the tests abort with `failed`.
-
-[1]: http://www-03.ibm.com/systems/power/software/aix/linux
-[2]: http://www.bullfreeware.com
diff --git a/cpp/BuildInstructionsLinux.md b/cpp/BuildInstructionsLinux.md
index 36b5e658737..2a656abda77 100644
--- a/cpp/BuildInstructionsLinux.md
+++ b/cpp/BuildInstructionsLinux.md
@@ -53,14 +53,15 @@ that do not include them. You can install these packages as shown below:
 
 ## Building Ice
 
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information. Pay
+particular attention to the variables that define the locations of the third-party
+libraries.
+
 In a command window, change to the `cpp` subdirectory:
 
     $ cd cpp
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information. Pay particular attention to the variables
-that define the locations of the third-party libraries.
-
 Now you're ready to build Ice:
 
     $ make
@@ -81,11 +82,11 @@ To build all the supported configurations and platforms:
 
 ### C++11 mapping
 
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
+The C++ source tree supports two different language mappings (C++98 and C++11).
+The default build uses the C++98 mapping. The C++11 mapping is a new mapping
+that uses new language features.
 
-To build the new C++11 mapping, use build configurations which are prefixed with
+To build the C++11 mapping, use build configurations that are prefixed with
 `cpp11`, for example:
 
     make CONFIGS=cpp11-shared
@@ -93,12 +94,12 @@ To build the new C++11 mapping, use build configurations which are prefixed with
 ## Installing a C++ Source Build
 
 Simply run `make install`. This will install Ice in the directory specified by
-the `<prefix>` variable in `config/Make.rules`.
+the `<prefix>` variable in `../config/Make.rules`.
 
 After installation, make sure that the `<prefix>/bin` directory is in your `PATH`.
 
 If you choose to not embed a `runpath` into executables at build time (see your
-build settings in `config/Make.rules`) or did not create a symbolic link from
+build settings in `../config/Make.rules`) or did not create a symbolic link from
 the `runpath` directory to the installation directory, you also need to add the
 library directory to your `LD_LIBRARY_PATH`.
 
@@ -116,8 +117,8 @@ When compiling Ice programs, you must pass the location of the `<prefix>/include
 directory to the compiler with the `-I` option, and the location of the library
 directory with the `-L` option. 
 
-If building a C++11 program, you must define `ICE_CPP11_MAPPING` macro during
-compilation with the `-D` option (`g++ -DICE_CPP11_MAPING`) and add
+If building a C++11 program, you must define the `ICE_CPP11_MAPPING` macro during
+compilation with the `-D` option (`g++ -DICE_CPP11_MAPPING`) and add
 the `++11` suffix to the library name when linking (such as `-lIce++11`).
 
 ## Running the Test Suite
@@ -135,7 +136,7 @@ This command is equivalent to:
 
     $ python allTests.py
     
-For C++11 mapping it also include the`--c++11` argument:
+For the C++11 mapping it also includes the `--c++11` argument:
 
     $ python allTests.py --c++11
 
diff --git a/cpp/BuildInstructionsMacOS.md b/cpp/BuildInstructionsMacOS.md
index ebecf058b12..c1f236a8fef 100644
--- a/cpp/BuildInstructionsMacOS.md
+++ b/cpp/BuildInstructionsMacOS.md
@@ -29,14 +29,15 @@ You can install LMDB and mcpp using [Homebrew][7]:
 
 ## Building Ice
 
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information. Pay
+particular attention to the variables that define the locations of the third-party
+libraries.
+
 In a command window, change to the `cpp` subdirectory:
 
     cd cpp
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information. Pay particular attention to the variables
-that define the locations of the third-party libraries.
-
 Now you're ready to build Ice:
 
     make
@@ -57,18 +58,18 @@ To build all the supported configurations and platforms:
 
 ### C++11 mapping
 
-The C++ source tree supports two different language mappings (C++98 and C++11),
-the default build uses the C++98 mapping. The C++11 mapping is a new mapping
-that uses the new language features.
+The C++ source tree supports two different language mappings (C++98 and C++11).
+The default build uses the C++98 mapping. The C++11 mapping is a new mapping
+that uses new language features.
 
-To build the new C++11 mapping, use build configurations which are prefixed with
+To build the C++11 mapping, use build configurations that are prefixed with
 `cpp11`, for example:
 
     make CONFIGS=cpp11-shared
 
 ### Ice Xcode SDK
 
-The build system supports building Xcode SDKs for Ice. These SDKs allow to
+The build system supports building Xcode SDKs for Ice. These SDKs allow you to
 easily develop Ice applications with Xcode. To build Xcode SDKs, use the
 `xcodesdk` configurations:
 
@@ -80,13 +81,13 @@ The Xcode SDKs are built into `ice/IceSDK`.
 ## Installing a C++ Source Build
 
 Simply run `make install`. This will install Ice in the directory specified by
-the `prefix` variable in `config/Make.rules`.
+the `prefix` variable in `../config/Make.rules`.
 
 After installation, make sure that the `<prefix>/bin` directory is in your
 `PATH`.
 
 If you choose to not embed a `runpath` into executables at build time (see your
-build settings in `config/Make.rules`) or did not create a symbolic link from
+build settings in `../config/Make.rules`) or did not create a symbolic link from
 the `runpath` directory to the installation directory, you also need to add the
 library directory to your `DYLD_LIBRARY_PATH`.
 
@@ -96,7 +97,7 @@ location of the library directory with the `-L` option.
 
 If building a C++11 program, you must define the `ICE_CPP11_MAPPING` macro
 during compilation with the `-D` option (for example `clang++
--DICE_CPP11_MAPING`) and add the `++11` suffix to the library name when linking
+-DICE_CPP11_MAPPING`) and add the `++11` suffix to the library name when linking
 (such as `-lIce++11`).
 
 The Ice Xcode SDKs are installed in `<prefix>/lib/IceSDK`.
@@ -116,14 +117,14 @@ This command is equivalent to:
 
     python allTests.py
 
-For C++11 mapping it also include the`--c++11` argument:
+For the C++11 mapping it also includes the `--c++11` argument:
 
     $ python allTests.py --c++11
 
 If everything worked out, you should see lots of `ok` messages. In case of a
 failure, the tests abort with `failed`.
 
-[1]: https://doc.zeroc.com/display/Ice37/Using+the+OS+X+Binary+Distribution
+[1]: https://doc.zeroc.com/display/Ice37/Using+the+macOS+Binary+Distribution
 [2]: https://doc.zeroc.com/display/Ice37/Supported+Platforms+for+Ice+3.7.0
 [3]: http://bzip.org
 [4]: http://expat.sourceforge.net
diff --git a/cpp/BuildInstructionsWindows.md b/cpp/BuildInstructionsWindows.md
index 4172f8e2a77..3729a555508 100644
--- a/cpp/BuildInstructionsWindows.md
+++ b/cpp/BuildInstructionsWindows.md
@@ -1,6 +1,6 @@
 # Building Ice for C++ on Windows
 
-This file describes how to build Ice for C++ from sources on Windows, and how
+This file describes how to build Ice for C++ from sources on Windows and how
 to test the resulting build.
 
 ZeroC provides [Ice binary distributions][1] for various platforms and compilers,
@@ -27,9 +27,9 @@ Ice has dependencies on a number of third-party libraries:
  - [mcpp][6] 2.7.2 (with patches)
 
 You do not need to build these packages yourself, as ZeroC supplies
-[NuGet][7] packages for all these third party dependencies.
+[NuGet][7] packages for all of these third-party dependencies.
 
-The Ice build system for Windows downloads and installs the NuGet command line
+The Ice build system for Windows downloads and installs the NuGet command-line
 executable and these NuGet packages when you build Ice for C++. The third-party
 packages are installed in the ``ice/cpp/msbuild/packages`` folder.
 
@@ -45,51 +45,47 @@ Using the first Command Prompt produces `Win32` binaries by default, while
 the second Command Promt produces `x64` binaries by default.
 
 In the Command Prompt, change to the `cpp` subdirectory:
-```
+
     cd cpp
-```
 
 Now you're ready to build Ice:
-```
-    Msbuild msbuild\ice.proj
-```
+
+    msbuild msbuild\ice.proj
 
 This builds the Ice for C++ SDK and the Ice for C++ test suite, with 
 Release binaries for the default platform.
 
-Set the Msbuild `Configuration` property to `Debug` to build debug binaries
+Set the MSBuild `Configuration` property to `Debug` to build debug binaries
 instead:
-```
-     MSbuild msbuild\ice.proj /p:Configuration=Debug
-```
+
+     msbuild msbuild\ice.proj /p:Configuration=Debug
 
 The `Configuration` property may be set to `Debug` or `Release`.
 
-Set the Msbuild `Platform` property to `Win32` or `x64` to build binaries
+Set the MSBuild `Platform` property to `Win32` or `x64` to build binaries
 for a specific platform, for example:
-```
-    MSbuild msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64
-```
+
+    msbuild msbuild\ice.proj /p:Configuration=Debug /p:Platform=x64
 
 You can also skip the build of the test suite with the `BuildDist` target:
-```
-    MSbuild msbuild\ice.proj /t:BuildDist /p:Platform=x64
-```
+
+    msbuild msbuild\ice.proj /t:BuildDist /p:Platform=x64
 
 If you want to build all supported platforms and configurations at once, use:
-```
-    MSbuild msbuild\ice.proj /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /p:BuildAllConfigurations=yes
 
 You can also sign the Ice binaries with Authenticode, by setting the following
 environment variables:
  - SIGN_CERTIFICATE to your Authenticode certificate
  - SIGN_PASSWORD to the certificate password
- 
-You can also build the test suite against the NuGet packages with:
-```
-    MSbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
-```
+
+If you want to run the test suite without building the entire source base, use this
+command:
+
+    msbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
+
+The build will automatically install ZeroC's official Ice binary NuGet packages if necessary.
 
 ## Building Ice for UWP
 
@@ -97,39 +93,33 @@ The steps are the same as for Building Ice for C++ above, except you must also u
 `UWP` target.
 
 To build Ice for UWP:
-```
-    Msbuild msbuild\ice.proj /t:UWPBuild
-```
+
+    msbuild msbuild\ice.proj /t:UWPBuild
 
 To skip the building of the test suite:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuildDist
-```
+
+    msbuild msbuild\ice.proj /t:UWPBuildDist
 
 To build all configurations:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuildDist /p:BuildAllConfigurations=yes
-```
 
-To build the test suite against the NuGet packages:
-```
-    MSbuild msbuild\ice.proj /t:UWPBuild /p:ICE_BIN_DIST=all
-```
+    msbuild msbuild\ice.proj /t:UWPBuildDist /p:BuildAllConfigurations=yes
+
+To run the test suite without building the entire source base:
+
+    msbuild msbuild\ice.proj /t:UWPBuild /p:ICE_BIN_DIST=all
 
 ## NuGet packages
 
 You can create a NuGet package with the following command:
-```
-    MSbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /t:NuGetPack /p:BuildAllConfigurations=yes
 
 This creates `zeroc.ice.v120\zeroc.ice.v120.nupkg`, `zeroc.ice.v140\zeroc.ice.v140.nupkg`
-or `zeroc.ice.v141\zeroc.ice.v141.nupkg` depending of the compiler you are using.
+or `zeroc.ice.v141\zeroc.ice.v141.nupkg` depending on the compiler you are using.
 
 To create UWP NuGet packages, use the `UWPNuGetPack` target instead:
-```
-    MSbuild msbuild\ice.proj /t:UWPNuGetPack /p:BuildAllConfigurations=yes
-```
+
+    msbuild msbuild\ice.proj /t:UWPNuGetPack /p:BuildAllConfigurations=yes
 
 This creates `zeroc.ice.uwp\zeroc.ice.uwp.nupkg`, `zeroc.ice.uwp.x64\zeroc.ice.uwp.x64.nupkg` 
 and `zeroc.ice.uwp.x86\zeroc.ice.uwp.x86.nupkg`.
@@ -138,19 +128,16 @@ and `zeroc.ice.uwp.x86\zeroc.ice.uwp.x86.nupkg`.
 
 Python is required to run the test suite. Additionally, the Glacier2 tests
 require the Python module `passlib`, which you can install with the command:
-```
+
     pip install passlib
-```
 
 After a successful source build, you can run the tests as follows:
-```
+
     python allTests.py
-```
 
-For C++11 mapping you need to use the `Cpp11-Debug` or `Cpp11-Release` configuration:
-```
-    python allTests.py --config Cpp11-Debug
-```
+For the C++11 mapping you need to use the `Cpp11-Debug` or `Cpp11-Release` configuration:
+
+    $ python allTests.py --config Cpp11-Debug
 
 If everything worked out, you should see lots of `ok` messages. In case of a
 failure, the tests abort with `failed`.
@@ -158,14 +145,13 @@ failure, the tests abort with `failed`.
 ## Running the Universal Windows Platform Test Suite
 
 In Visual Studio 2015, open the solution file:
-```
+
     cpp\msbuild\ice.testuwp.sln
-```
 
 Now select the configuration that matches the settings that you used to build
 Ice for UWP.
 
-To run the UWP Test suite application you can deploy the application using "Deploy
+To run the UWP Test suite application, you can deploy the application using "Deploy
 Solution" in the "Build" menu. Once deployed, you can start the application from
 the Start Menu by clicking the "Ice Test Suite" icon.
 
@@ -173,17 +159,16 @@ In the test suite application, selecting "uwp" for the Server field allows you
 to run tests with TCP and WS protocols supported by the UWP server side.
 
 You can also use C++, C# or Java servers to run the tests, which allows you to
-use  additional SSL and WSS protocols.
+use additional SSL and WSS protocols.
 
 To use servers from C++, C# or Java language mappings, you need to build the
 tests for the desired language mapping.
 
 The test controller server is implemented in Java. Refer to the build
-instructions in java subdirectory for information on building the test
+instructions in the java subdirectory for information on building the test
 controller. Use the following command to start the test controller:
-```
+
     python scripts/TestController.py
-```
 
 In the "Ice Test Suite" Windows Store application, select the Server language
 mapping and Protocol you want to use.
diff --git a/csharp/BuildInstructions.md b/csharp/BuildInstructions.md
index 69e3c57176a..009ab083e73 100644
--- a/csharp/BuildInstructions.md
+++ b/csharp/BuildInstructions.md
@@ -11,7 +11,7 @@ for the supported platforms.
 Ice for .NET was extensively tested using the operating systems and compiler
 versions listed for our [supported platforms][2].
 
-The build requires the [Ice Builder for Visual Studio][3], you must install
+The build requires the [Ice Builder for Visual Studio][3]. You must install
 version 4.3.6 or greater to build Ice.
 
 ## Compiling Ice for .NET with Visual Studio
@@ -19,7 +19,8 @@ version 4.3.6 or greater to build Ice.
 ### Preparing to Build
 
 The build system requires the `slice2cs` compiler from Ice for C++. If you have
-not built Ice for C++ in this source distribution, refer to [C++ build instructions](../cpp/BuildInstructionsWindows.md).
+not built Ice for C++ in this source distribution, refer to the
+[C++ build instructions](../cpp/BuildInstructionsWindows.md).
 
 ### Building Ice for .NET
 
@@ -29,13 +30,16 @@ Open a Visual Studio command prompt and change to the `csharp` subdirectory:
 
 To build the Ice assemblies, services and tests, run
 
-    MSBuild msbuild\ice.proj
+    msbuild msbuild\ice.proj
 
-It is also possible to build the test suite using the binary NuGet packages, use:
+Upon completion, the Ice assemblies are placed in the `Assemblies` subdirectory.
 
-    MSbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
+If you want to run the test suite without building the entire source base, use this
+command:
 
-Upon completion, the Ice assemblies are placed in the `Assemblies` subdirectory.
+    msbuild msbuild\ice.proj /p:ICE_BIN_DIST=all
+
+The build will automatically install ZeroC's official Ice binary NuGet packages if necessary.
 
 ## Running the .NET Tests
 
@@ -59,17 +63,17 @@ Ice invokes unmanaged code to implement the following features:
 - Protocol compression
 - Signal processing in the Ice.Application class
 
-if you do not require these features and prefer that the Ice run time use only 
-managed code, you can build using the `Debug-Managed` or `Release-Manage` 
-configurations.
+if you do not require these features and prefer that the Ice run time use only
+managed code, you can build using the `Debug-Managed` or `Release-Managed`
+configurations:
 
-    MSBuild msbuild\ice.proj /p:Configuration=Release-Managed
+    msbuild msbuild\ice.proj /p:Configuration=Release-Managed
 
 ## NuGet packages
 
-To create a NuGet package for the distribution use the following command:
+To create a NuGet package for the distribution, use the following command:
 
-    MSbuild msbuild\ice.proj /t:NuGetPack
+    msbuild msbuild\ice.proj /t:NuGetPack
 
 This will create `zeroc.ice.net\zeroc.ice.net.nupkg`.
 
diff --git a/java-compat/BuildInstructions.md b/java-compat/BuildInstructions.md
index 6218c35b4f0..2e40ae77b85 100644
--- a/java-compat/BuildInstructions.md
+++ b/java-compat/BuildInstructions.md
@@ -25,7 +25,7 @@ generated Java files to your target platform.
 
 ### Java Version
 
-Ice for Java requires J2SE 1.7.0 or later.
+Ice for Java requires J2SE 1.8.0 or later.
 
 Make sure that the `javac` and `java` commands are present in your PATH.
 
@@ -34,9 +34,7 @@ Make sure that the `javac` and `java` commands are present in your PATH.
 Ice for Java uses the [Gradle][3] build system, and includes the Gradle wrapper
 version 2.4 in the distribution. You cannot build the Ice for Java source
 distribution without an Internet connection. Gradle will download all required
-packages automatically. These packages are listed below. Gradle will
-automatically download any necessary build artifacts from ZeroC's Maven
-repository located at
+packages automatically from ZeroC's Maven repository located at
 
     http://repo.zeroc.com/nexus/content/repositories/thirdparty
 
@@ -61,7 +59,7 @@ therefore add significant latency to Ice requests.*
 
 ### Preparing to Build
 
-The build system  requires the Slice compilers from Ice for C++. If you have
+The build system requires the Slice to Java compiler from Ice for C++. If you have
 not built Ice for C++ in this source distribution, you must set the `ICE_HOME`
 environment variable with the path name of your Ice installation. For example,
 on Unix:
@@ -74,12 +72,15 @@ On Windows:
     > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.7b0 (MSI installation)
 
 On Windows if you are using Ice for C++ from a source distribution, you must
-set `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the
-platform and configuration used in your C++ builds:
+set the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the
+platform and configuration used in your C++ build:
 
     > set CPP_PLATFORM=x64
     > set CPP_CONFIGURATION=Debug
 
+The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported
+values for `CPP_CONFIGURATION` are `Debug` and `Release`.
+
 Before building Ice for Java, review the settings in the file
 `gradle.properties` and edit as necessary.
 
@@ -100,23 +101,24 @@ these commands:
 ## Installing Ice for Java
 
 To install Ice for Java in the directory specified by the `prefix` variable in
-`gradle.properties` run the following command
+`gradle.properties` run the following command:
 
     > gradlew install
 
 The installation installs the following JAR files to `<prefix>/lib`.
 
-    glacier2-3.7b0.jar
-    ice-3.7b0.jar
-    icebox-3.7b0.jar
-    icediscovery-3.7b0.jar
-    icegrid-3.7b0jar
+    glacier2-compat-3.7.0-beta0.jar
+    ice-compat-3.7.0-beta0.jar
+    icebox-compat-3.7.0-beta0.jar
+    icebt-compat-3.7.0-beta0.jar
+    icediscovery-compat-3.7.0-beta0.jar
+    icegrid-compat-3.7.0-beta0jar
     icegridgui.jar
-    icelocatordiscovery-3.7b0.jar
-    icepatch2-3.7b0.jar
-    icestorm-3.7b0jar
+    icelocatordiscovery-compat-3.7.0-beta0.jar
+    icepatch2-compat-3.7.0-beta0.jar
+    icestorm-compat-3.7.0-beta0jar
 
-POM files are also installed for ease of deployment to a maven-based
+POM files are also installed for ease of deployment to a Maven-based
 distribution system.
 
 ## Running the Java Tests
diff --git a/java/BuildInstructions.md b/java/BuildInstructions.md
index 3078b01cb71..2d782b75526 100644
--- a/java/BuildInstructions.md
+++ b/java/BuildInstructions.md
@@ -40,9 +40,10 @@ support, as the Metrics Graph feature is enabled dynamically.
 Ice for Java uses the [Gradle][3] build system, and includes the Gradle wrapper
 version 2.4 in the distribution. You cannot build the Ice for Java source
 distribution without an Internet connection. Gradle will download all required
-packages automatically. These packages are listed below. Gradle will
-automatically download any necessary build artifacts from ZeroC's Maven
-repository located at
+distribution without an Internet connection. Gradle will download all required
+packages automatically from ZeroC's Maven repository located at
+
+    http://repo.zeroc.com/nexus/content/repositories/thirdparty
 
 ### Bzip2 Compression
 
@@ -96,7 +97,7 @@ The Maven package id for the application bundler package is as follows:
 
 ### Preparing to Build
 
-The build system requires the Slice compilers from Ice for C++. If you have
+The build system requires the Slice to Java compiler from Ice for C++. If you have
 not built Ice for C++ in this source distribution, you must set the `ICE_HOME`
 environment variable with the path name of your Ice installation. For example,
 on Unix:
@@ -109,14 +110,14 @@ On Windows:
     > set ICE_HOME=C:\Program Files (x86)\ZeroC\Ice-3.7b0 (MSI installation)
 
 On Windows if you are using Ice for C++ from a source distribution, you must
-set `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the
-platform and configuration used in your C++ builds:
+set the `CPP_PLATFORM` and `CPP_CONFIGURATION` environment variables to match the
+platform and configuration used in your C++ build:
 
     > set CPP_PLATFORM=x64
     > set CPP_CONFIGURATION=Debug
 
-The supported values for `CPP_PLATFORM` are `Win32` and `x64`and the supported
-values for `CPP_CONFIGURATION` are `Debug` and `Release`
+The supported values for `CPP_PLATFORM` are `Win32` and `x64` and the supported
+values for `CPP_CONFIGURATION` are `Debug` and `Release`.
 
 Before building Ice for Java, review the settings in the file
 `gradle.properties` and edit as necessary.
@@ -138,23 +139,25 @@ these commands:
 ## Installing Ice for Java
 
 To install Ice for Java in the directory specified by the `prefix` variable in
-`gradle.properties` run the following command
+`gradle.properties` run the following command:
 
     > gradlew install
 
-The installation installs the following JAR files to `<prefix>/lib`.
+The following JAR files will be installed to `<prefix>/lib`.
 
-    glacier2-3.7b0.jar
-    ice-3.7b0.jar
-    icebox-3.7b0.jar
-    icediscovery-3.7b0.jar
-    icegrid-3.7b0.jar
+    glacier2-3.7.0-beta0.jar
+    ice-3.7.0-beta0.jar
+    icebox-3.7.0-beta0.jar
+    icebt-3.7.0-beta0.jar
+    icediscovery-3.7.0-beta0.jar
+    icegrid-3.7.0-beta0.jar
     icegridgui.jar
-    icelocatordiscovery-3.7b0.jar
-    icepatch2-3.7b0.jar
-    icestorm-3.7b0.jar
+    icelocatordiscovery-3.7.0-beta0.jar
+    icepatch2-3.7.0-beta0.jar
+    icessl-3.7.0-beta0.jar
+    icestorm-3.7.0-beta0.jar
 
-POM files are also installed for ease of deployment to a maven-based
+POM files are also installed for ease of deployment to a Maven-based
 distribution system.
 
 ## Running the Java Tests
@@ -189,9 +192,8 @@ You can start the tool with the following command:
 
     > java -jar icegridgui.jar
 
-On macOS, there is also an application bundle named IceGrid GUI. You can start
-the IceGrid GUI tool by double-clicking the IceGrid GUI icon in Finder.
-
+On macOS, the build also creates an application bundle named IceGrid GUI.
+You can start the IceGrid GUI tool by double-clicking the IceGrid GUI icon in Finder.
 
 [1]: https://zeroc.com/distributions/ice
 [2]: https://doc.zeroc.com/display/Ice37/Supported+Platforms+for+Ice+3.7.0
diff --git a/js/BuildInstructions.md b/js/BuildInstructions.md
index ae4092988c9..c67c02f4133 100644
--- a/js/BuildInstructions.md
+++ b/js/BuildInstructions.md
@@ -9,7 +9,7 @@ supported platforms.
 To build Ice for JavaScript you must have the following:
 
 - The `slice2js` compiler from Ice for C++. If you have not built Ice for C++
-  in this source distribution, refer to [C++ build instructions](../cpp/BuildInstructions.md).
+  in this source distribution, refer to the [C++ build instructions](../cpp/BuildInstructions.md).
 - Node.js 4.6 or later
 
 ## Building the JavaScript libraries and NodeJS packages
@@ -51,7 +51,7 @@ password. This is necessary to configure the trust setting for the HTTP
 server certificate, which will enable you to connect to the HTTP server
 with SSL via your web browser.
 
-The test page (http://127.0.0.1:8080) will be opened using the system default
+The test page (http://127.0.0.1:8080) will be opened using the system's default
 browser.
 
 ### Browser Information
@@ -62,7 +62,7 @@ The browser-based tests allow you to choose whether to run the tests over
 non-secure WebSocket (WS) or secure WebSocket (WSS) connections. This
 distribution includes a self-signed certificate used for securing WSS
 connections, located in `certs/cacert.pem`. If you select WSS, the page
-will automatically reload if necessary to connect to the HTTPS port 9090.
+will automatically reload if necessary to connect to HTTPS port 9090.
 To successfully run the tests over WSS, additional action may be necessary
 depending on the browser you're using:
 
@@ -123,7 +123,7 @@ Next go to _Settings -> Security -> Install from storage_, and choose
 
 ## Installing a Source Build
 
-After a successful build, you can generate a npm package by running the
+After a successful build, you can generate an npm package by running the
 following command:
 
     > npm pack
diff --git a/objective-c/BuildInstructions.md b/objective-c/BuildInstructions.md
index a6810f0a612..582c6529b6c 100644
--- a/objective-c/BuildInstructions.md
+++ b/objective-c/BuildInstructions.md
@@ -13,11 +13,11 @@ our [supported platforms][2].
 
 ## Building Ice for Objective-C
 
-The build of Ice for Objective-C requires to first build Ice for C++ in the
+The build of Ice for Objective-C requires that you first build Ice for C++ in the
 `cpp` subdirectory.
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information.
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information.
 
 Change to the Ice for Objective-C source subdirectory:
 
@@ -27,8 +27,8 @@ Run `make` to build the Ice Objective-C libraries.
 
 ### Build configurations and platforms
 
-The Objective-C source tree supports multiple build configurations and
-platforms. To see the supported configurations and platforms:
+The Objective-C source tree supports multiple build configurations and platforms.
+To see the supported configurations and platforms:
 
     make print V=supported-configs
     make print V=supported-platforms
@@ -39,7 +39,7 @@ To build all the supported configurations and platforms:
 
 ### Ice Xcode SDK
 
-The build system supports building Xcode SDKs for Ice. These SDKs allow to
+The build system supports building Xcode SDKs for Ice. These SDKs allow you to
 easily develop Ice applications with Xcode. To build Xcode SDKs, use the
 `xcodesdk` configurations:
 
@@ -50,7 +50,7 @@ The Xcode SDKs are built into `ice/IceSDK`.
 ## Installing an Objective-C Source Build
 
 Simply run `make install`. This will install Ice in the directory specified by
-the `prefix` variable in `config/Make.rules`.
+the `prefix` variable in `../config/Make.rules`.
 
 When compiling Ice programs, you must pass the location of the
 `<prefix>/include` directory to the compiler with the `-I` option, and the
@@ -70,5 +70,5 @@ This command is equivalent to:
 If everything worked out, you should see lots of `ok` messages. In case of a
 failure, the tests abort with `failed`.
 
-[1]: https://doc.zeroc.com/display/Ice37/Using+the+OS+X+Binary+Distribution
+[1]: https://doc.zeroc.com/display/Ice37/Using+the+macOS+Binary+Distribution
 [2]: https://doc.zeroc.com/display/Ice37/Supported+Platforms+for+Ice+3.7.0
diff --git a/php/BuildInstructionsLinuxMacOS.md b/php/BuildInstructionsLinuxMacOS.md
index e0b6c3717c4..ec97ecbfcc5 100644
--- a/php/BuildInstructionsLinuxMacOS.md
+++ b/php/BuildInstructionsLinuxMacOS.md
@@ -13,22 +13,22 @@ versions listed for our [supported platforms][2].
 
 ## Building the PHP Extension
 
-The build of Ice for PHP requires to first build Ice for C++ in the `cpp`
+The build of Ice for PHP requires that you first build Ice for C++ in the `cpp`
 subdirectory.
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information.
+From the top-level source directory, edit `config/Make.rules` to establish
+your build configuration. The comments in the file provide more information.
 
 Our source code only supports building Ice for PHP as a dynamic PHP extension;
 the product of the build is a shared library that you must configure PHP to
 load.
 
-First, change to the `php` source subdirectory:
+Change to the `php` source subdirectory:
 
     $ cd php
 
 Ensure that `php` and `php-config` for the version of PHP you wish to
-build against are first in your path.
+build against are first in your PATH.
 
 Run `make` to build the extension.
 
@@ -83,8 +83,9 @@ PHP will need to be able to locate the libraries for the Ice run-time libraries
 and its third-party dependencies. These libraries are named as follows:
 
     libIce
-    libIceUtil
-    libSlice
+    libIceDiscovery
+    libIceLocatorDiscovery
+    libIceSSL
     libbz2
 
 In general, these libraries must reside in a directory of the user's PATH. For
diff --git a/php/BuildInstructionsWindows.md b/php/BuildInstructionsWindows.md
index 5b3a6121c16..2df570cb21d 100644
--- a/php/BuildInstructionsWindows.md
+++ b/php/BuildInstructionsWindows.md
@@ -11,24 +11,25 @@ supported platforms.
 Ice for PHP was extensively tested using the operating systems and compiler
 versions listed for our [supported platforms][2].
 
-The build requires the [Ice Builder for Visual Studio][8], you must install
+The build requires the [Ice Builder for Visual Studio][8]. You must install
 version 4.3.6 or greater to build Ice.
 
 ### Preparing to Build
 
 The build system requires the slice2php compiler from Ice for C++. If you have not
-built Ice for C++ in this source distribution, refer to [C++ build instructions](../cpp/BuildInstructionsWindows.md)
+built Ice for C++ in this source distribution, refer to the
+[C++ build instructions](../cpp/BuildInstructionsWindows.md).
 
 ## Building the PHP Extension
 
-Open a command prompt for example, when using Visual Studio 2015, you have
+Open a command prompt. For example, when using Visual Studio 2015, you have
 several alternatives:
 
 - VS2015 x86 Native Tools Command Prompt
 - VS2015 x64 Native Tools Command Prompt
 
-Using the first configurations produces 32-bit binaries, while the second
-configurations produce 64-bit binaries.
+Using the first configuration produces 32-bit binaries, while the second
+configuration produces 64-bit binaries.
 
 In the command window, change to the `php` subdirectory:
 
@@ -36,30 +37,31 @@ In the command window, change to the `php` subdirectory:
 
 Now you're ready to build Ice for PHP:
 
-    Msbuild msbuild\ice.proj
+    msbuild msbuild\ice.proj
 
 This will build the extension in `Release` configuration and using the command
-prompt default platform, for `x64` platform the extension will be placed in
-`lib\x64\Release\php_ice.dll` and for `Win32` platform the extension will be
+prompt default platform. For the `x64` platform the extension will be placed in
+`lib\x64\Release\php_ice.dll` and for the `Win32` platform the extension will be
 placed in `lib\Win32\Release\php_ice.dll`.
 
-The default configuration builds the extension agains the Thread Safe PHP runtime,
-you can build with the Non Thread Safe using the `NTS-Release` and `NTS-Debug` 
-configurations.
+The default configuration builds the extension against the thread-safe PHP run time.
+You can build with the non-thread-safe run time using the `NTS-Release` and `NTS-Debug` 
+configurations:
 
-        > MSbuild msbuild\ice.proj /p:Configuration=NTS-Release
+    msbuild msbuild\ice.proj /p:Configuration=NTS-Release
 
-The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for x64 builds 
-and `lib\Win32\Release\php_ice_nts.dll` for `Win32` builds.
+The extension will be placed in `lib\x64\Release\php_ice_nts.dll` directory for
+`x64` builds and `lib\Win32\Release\php_ice_nts.dll` for `Win32` builds.
 
-The extension is by default built with namespaces enabled it is possible to build the PHP
-extension with namespaces disabled by setting the Msbuild `PhpUseNamespaces` property to `no`
+The extension is built by default with namespaces enabled. You can build the PHP
+extension with namespaces disabled by setting the MSBuild property `PhpUseNamespaces`
+to `no`:
 
-        > MSbuild msbuild\ice.proj /p:PhpUseNamespaces=no
+    msbuild msbuild\ice.proj /p:PhpUseNamespaces=no
 
-It is also possible to build the test suite using the binary Ice distribution, use:
+It is also possible to build the test suite using the binary Ice distribution:
 
-    MSbuild msbuild\ice.proj /p:UseBinDist=yes /p:"IceHome=C:\Program Files\ZeroC\Ice-3.7b0"
+    msbuild msbuild\ice.proj /p:UseBinDist=yes /p:"IceHome=C:\Program Files\ZeroC\Ice-3.7b0"
 
 ## Installing the PHP Extension
 
@@ -94,14 +96,14 @@ PHP will need to be able to locate the libraries for the Ice run-time libraries
 and its third-party dependencies. On Windows, these DLLs are required:
 
     bzip2.dll
-    ice37a3.dll
+    ice37b0.dll
     icediscovery37b0.dll
     icelocatordiscovery37b0.dll
     icessl37b0.dll
 
 In general, these libraries must reside in a directory of the user's PATH. For
-ISS configured to run PHP as FastCGI the simple is to copy the libraries next to
-the php-cgi.exe in C:\Program Files\iis express\PHP\v7.0
+IIS configured to run PHP as FastCGI, the simplest solution is to copy the
+libraries next to the php-cgi.exe in C:\Program Files\iis express\PHP\v7.0.
 
 You can verify that the Ice extension is installed properly by examining the
 output of the `php -m` command, or by calling the `phpInfo()` function from a
@@ -138,7 +140,7 @@ the following directive:
 The test subdirectory contains PHP implementations of the core Ice test suite.
 Python is required to run the test suite.
 
-The test suites require that the Ice for C++ tests be built in the `cpp`
+The test suites also require that the Ice for C++ tests be built in the `cpp`
 subdirectory of this source distribution. In addition, the scripts require
 that the CLI version of the PHP interpreter be available in your PATH.
 
diff --git a/python/BuildInstructionsLinuxMacOS.md b/python/BuildInstructionsLinuxMacOS.md
index bb019a45494..13bba321f96 100644
--- a/python/BuildInstructionsLinuxMacOS.md
+++ b/python/BuildInstructionsLinuxMacOS.md
@@ -23,8 +23,8 @@ compatible with the one used to build Ice for C++.
 The build of Ice for Python requires to first build Ice for C++ in the `cpp`
 subdirectory.
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information.
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information.
 
 Change to the Ice for Python source subdirectory:
 
diff --git a/python/BuildInstructionsWindows.md b/python/BuildInstructionsWindows.md
index 21e3630db9c..4babc4ed237 100644
--- a/python/BuildInstructionsWindows.md
+++ b/python/BuildInstructionsWindows.md
@@ -12,81 +12,84 @@ Ice for Python is expected to build and run properly on Windows and was
 extensively tested using the operating systems and compiler versions listed for
 our [supported platforms][2].
 
-The build requires the [Ice Builder for Visual Studio][8], you must install
-version 4.2.0 or greater to build Ice.
+The build requires the [Ice Builder for Visual Studio][8]. You must install
+version 4.3.6 or greater to build Ice.
 
 ### Python Versions
 
-Ice for Python supports Python versions 2.6, 2.7, 3.3, 3.4 or 3.5. Note however
-that your Python installation must have been built with a C++ compiler that is
-compatible with the one used to build Ice for C++.
+Ice for Python supports Python versions 2.7 or 3.6. Note however that your
+Python installation must have been built with a C++ compiler that is compatible
+with the one used to build Ice for C++.
 
 ## Building the Python Extension
 
 The Python interpreter is readily available on Windows platforms. You can build
 it yourself using Microsoft Visual C++, or obtain a binary distribution from the
-Python web site. The Python 3.5.x binary distribution is compiled with Visual
-C++ 14, Python 3.4.x and Python 2.7.x are compiled with Visual C++ 10, you
-should compile the Ice extension with the same Visual C++ version that your
-Python binary distribution was compiled.
+Python web site. The Python 3.6.x binary distribution is compiled with Visual
+C++ 14, while Python 2.7.x is compiled with Visual C++ 10. You should compile the
+Ice extension with the same Visual C++ version as your Python binary distribution.
 
-Using the first configurations produces 32-bit binaries, while the second
-configurations produce 64-bit binaries.
+Open a command prompt. For example, when using Visual Studio 2015, you have
+several alternatives:
+
+- VS2015 x86 Native Tools Command Prompt
+- VS2015 x64 Native Tools Command Prompt
+
+Using the first configuration produces 32-bit binaries, while the second
+configuration produces 64-bit binaries.
 
 Change to the Ice for Python source subdirectory:
 
     > cd python
 
-You must built Ice for C++ from the `cpp` subdirectory, if you have not done so
-review cpp\BuildInstructionsWindows.md first.
+You must built Ice for C++ from the `cpp` subdirectory. If you have not done so,
+refer to the [C++ build instructions](../cpp/BuildInstructionsWindows.md).
 
-Building the extension:
+Build the extension:
 
-    > MSbuild msbuild\ice.proj
+    > msbuild msbuild\ice.proj
 
-This will build the extension in `Release` configuration and using the command
-prompt default platform, for `x64` platform the extension will be placed in
-`python\x64\Release\IcePy.pyd` and for `Win32` platform the extension will be
-paced in `python\Win32\Release\IcePy.pyd`.
+This will build the extension in `Release` configuration using the command
+prompt's default platform. For the `x64` platform, the extension will be placed in
+`python\x64\Release\IcePy.pyd`, and for the `Win32` platform the extension will be
+placed in `python\Win32\Release\IcePy.pyd`.
 
-If you want to build a debug version of the extension you can to so by setting
+If you want to build a debug version of the extension, you can do so by setting
 the MSBuild `Configuration` property to `Debug`:
 
-    > MSbuild msbuild\ice.proj /p:Configuration=Debug
+    > msbuild msbuild\ice.proj /p:Configuration=Debug
 
-The debug version of the extension for `x64` platform will be placed in
-`python\x64\Debug\IcePy_d.pyd` and for `Win32` platform it will be placed in
+The debug version of the extension for the `x64` platform will be placed in
+`python\x64\Debug\IcePy_d.pyd` and for the `Win32` platform it will be placed in
 `python\Win32\Debug\IcePy_d.pyd`.
 
 > *For Debug builds a debug version of the Python interpreter must be installed.*
 
 The supported values for the `Configuration` property are `Debug` and `Release`.
 
-If you wan to build the extension for other platform that the command prompt
-default platform, you need to set the MSbuild `Platform` property, the supported
+If you want to build the extension for a different platform than the command prompt's
+default platform, you need to set the MSBuild property `Platform`. The supported
 values for this property are `Win32` and `x64`.
 
-The following command will build the extension `x64` platform binaries with
+The following command will build the `x64` platform binaries with the
 `Release` configuration:
 
-  > MSbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64
+  > msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64
 
-And the next command will build the extension `Win32` platform binaries with
+This command will build the `Win32` platform binaries with the
 `Release` configuration:
 
-  > MSbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32
+  > msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=Win32
 
-> *When using the MSBuild Platform property the build platform doesn't depend on
-the command prompt default platform*
+> *When using the MSBuild Platform property, the build platform doesn't depend on
+the command prompt's default platform.*
 
-The build will use a default Python location defined in
-`python\msbuild\ice.props`, it can be override by setting the `PythonHome`
-MSBuild property.
+The build will use a default location for Python defined in
+`python\msbuild\ice.props`. You can override it by setting the `PythonHome`
+MSBuild property. For example, the following command will use Python installation
+from `C:\Python36-AMD64` instead of the default location:
 
-The following command will use Python installation from `C:\Python35-AMD64`
-instead of the default location:
-
-    > MSbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python35-AMD64
+    > msbuild msbuild\ice.proj /p:Configuration=Release /p:Platform=x64 /p:PythonHome=C:\Python36-AMD64
 
 ## Configuring your Environment for Python
 
@@ -99,7 +102,6 @@ subdirectory. For example, if the Ice for Python extension is installed in
 
     > set PYTHONPATH=C:\Ice\python;C:\Ice\python\Win32\Release
 
-
 ## Running the Python Tests
 
 After a successful build, you can run the tests as follows:
diff --git a/ruby/BuildInstructionsLinuxMacOS.md b/ruby/BuildInstructionsLinuxMacOS.md
index b9ffcc2c747..6e224330838 100644
--- a/ruby/BuildInstructionsLinuxMacOS.md
+++ b/ruby/BuildInstructionsLinuxMacOS.md
@@ -1,4 +1,4 @@
-# Building Ice for Ruby on Linux
+# Building Ice for Ruby on Linux and macOS
 
 This file describes how to build and install Ice for Ruby from source code on
 Linux and macOS. If you prefer, you can also download [binary distributions][1]
@@ -33,11 +33,11 @@ environment variable to the installation directory. For example:
 
     $ export RUBY_HOME=/opt/ruby
 
-The build of Ice for Python requires to first build Ice for C++ in the `cpp`
+The build of Ice for Python requires that you first build Ice for C++ in the `cpp`
 subdirectory.
 
-Edit `config/Make.rules` to establish your build configuration. The comments in
-the file provide more information.
+From the top-level source directory, edit `config/Make.rules` to establish your
+build configuration. The comments in the file provide more information.
 
 Change to the Ice for Ruby source subdirectory:
 
@@ -51,7 +51,7 @@ You can perform an automated installation with the following command:
 
     $ make install
 
-This process uses the `prefix` variable in `config/Make.rules` as the
+This process uses the `prefix` variable in `../config/Make.rules` as the
 installation's root directory. The subdirectory `<prefix>/ruby` is created as a
 copy of the local `ruby` directory and contains the Ice for Ruby extension
 library as well as Ruby source code. Using this installation method requires