diff --git a/readme-windows.txt b/readme-windows.txt
index 7917a90a..d8cd5696 100644
--- a/readme-windows.txt
+++ b/readme-windows.txt
@@ -11,8 +11,9 @@ separately in the case that they are not already available.
 Capabilities
 ------------
 
-The network support in Windows is severely limited. The broker is limited to approximately
-1024 MQTT connections.
+Some versions of Windows have limitations on the number of concurrent
+connections. Non-server versions have been reported to be limited to
+approximately 1024 connections.
 
 
 Websockets
@@ -20,7 +21,7 @@ Websockets
 
 The broker executables provided in the installers do not have Websockets support enabled.
 If you wish to have a version of the broker with Websockets support, you will need to compile
-libwebsockets version v1.3-chrome37-firefox30 yourself and mosquitto version 1.4 yourself.
+libwebsockets version v1.7 onwards because no Windows binaries are provided.
 
 Please note that on Windows, libwebsockets limits connections to a maximum of 64 clients.
 
diff --git a/readme.md b/readme.md
index 20e20d0d..3f420632 100644
--- a/readme.md
+++ b/readme.md
@@ -2,7 +2,11 @@ Mosquitto
 =========
 
 Mosquitto is an open source implementation of a server for version 3.1 and
-3.1.1 of the MQTT protocol.
+3.1.1 of the MQTT protocol. It also includes a C and C++ client library, and
+the `mosquitto_pub` and `mosquitto_sub` utilities for publishing and
+subscribing.
+
+## Links
 
 See the following links for more information on MQTT:
 
@@ -12,10 +16,60 @@ See the following links for more information on MQTT:
 Mosquitto project information is available at the following locations:
 
 - Main homepage: <http://mosquitto.org/>
-- Find existing bugs: <https://bugs.eclipse.org/bugs/buglist.cgi?product=Mosquitto>
-- Submit a bug: <https://bugs.eclipse.org/bugs/enter_bug.cgi?product=Mosquitto>
-- Source code repository: <http://git.eclipse.org/c/mosquitto/org.eclipse.mosquitto.git/>
+- Bug reports: <https://github.com/eclipse/mosquitto/issues>
+- Source code repository: <https://github.com/eclipse/mosquitto>
 
 There is also a public test server available at <http://test.mosquitto.org/>
 
+## Installing
+
+See <http://mosquitto.org/download/> for details on installing binaries for
+various platforms.
+
+## Quick start
+
+If you have installed a binary package the broker should have been started
+automatically. If not, it can be started with a basic configuration:
+
+    mosquitto
+
+Then use `mosquitto_sub` to subscribe to a topic:
+
+    mosquitto_sub -t 'test/topic' -v
+
+And to publish a message:
+
+    mosquitto_pub -t 'test/topic' -m 'hello world'
+
+## Documentation
+
+Documentation for the broker, clients and client library API can be found in
+the man pages, which are available online at <http://mosquitto.org/man/>. There
+are also pages with an introduction to the features of MQTT, the
+`mosquitto_passwd` utility for dealing with username/passwords, and a
+description of the configuration file options available for the broker.
+
+Detailed client library API documentation can be found at <http://mosquitto.org/api/>
+
+## Building from source
+
+To build from source the recommended route for end users is to download the
+archive from <http://mosquitto.org/download/>.
+
+On Windows and Mac, use `cmake` to build. On other platforms, just run `make`
+to build. For Windows, see also `readme-windows.md`.
+
+If you are building from the git repository then the documentation will not
+already be built. Use `make binary` to skip building the man pages, or install
+`docbook-xsl` on Debian/Ubuntu systems.
+
+### Build Dependencies
+
+* c-ares (libc-ares2-dev on Debian based systems) - disable with `make WITH_DNS_SRV=no`
+* libuuid (uuid-dev) - disable with `make WITH_UUID=no`
+* libwebsockets (libwebsockets-dev) - enable with `make WITH_LIBWEBSOCKETS=yes`
+* openssl (libssl-dev on Debian based systems) - disable with `make WITH_TLS=no`
+
+## Credits
+
 Mosquitto was written by Roger Light <roger@atchoo.org>