improve docs

Author: mbasso

README.md

@@ -20,10 +20,14 @@
 
 ## Motivation
 
-asm-dom is a minimal WebAssembly virtual DOM to build C++ Web Apps. This means that you can write an entire Web App in C++ and compile it to WebAssembly (or asmjs as fallback) using [Emscripten](http://kripken.github.io/emscripten-site/), asm-dom will call DOM APIs for you. This will produce an app that `aims to execute at native speed by taking advantage of common hardware capabilities`, also, you can use your C/C++ code without any change, you haven't to create a binding layer to use it (as we have to do if we want to use a C++ lib from JS). Basically we are creating an app in C++ that call javascript if needed instead of the opposite. You can write only once in C++ and share as much code as possible with desktop/mobile apps and web site. If you are interested in performance, please see [this](https://github.com/mbasso/asm-dom/tree/master/benchmarks).
+asm-dom is a minimal WebAssembly virtual DOM to build C++ Web Apps. You can write an entire Web App in C++ and compile it to WebAssembly (or asmjs as fallback) using [Emscripten](http://kripken.github.io/emscripten-site/), asm-dom will call DOM APIs for you. This will produce an app that `aims to execute at native speed by taking advantage of common hardware capabilities`, also, you can use your C/C++ code without any change, you haven't to create a binding layer to use it (as we have to do if we want to use a C++ lib from JS). Basically we are creating an app in C++ that call javascript if needed instead of the opposite. You can write only once in C++ and share as much code as possible with desktop/mobile apps and web site. If you want to learn more about performance, please see [this](https://github.com/mbasso/asm-dom/tree/master/benchmarks).
+
+*How can I structure my application with asm-dom?*
 
 asm-dom is a low-level virtual DOM library. It is unopinionated with regards to how you should structure your application.
 
+*How did you come up with the concept of asm-dom?*
+
 At the beginning asm-dom is born from the idea to test the powerful of WebAssembly in a common use case that is not gaming, VR, AR or Image / video editing. Unfortunately, at the moment, [GC/DOM Integration](http://webassembly.org/docs/future-features/) is a future feature 🦄, so, asm-dom isn't totally developed in wasm. All interactions with the DOM are written in Javascript. This is a big disadvantage because of the overhead of the binding between JS and WASM, in the future asm-dom will be even more powerful, anyway results are satisfying.
 
 ## Inline Example

benchmarks/README.md

@@ -6,11 +6,11 @@
 
 ---
 
-In this directory you can find some code to measure the performance of asm-dom. You can find the results of asm-dom and [snabbdom](https://github.com/snabbdom/snabbdom), this allows you to make a comparison between the performance of asm-dom and a js virtual DOM. Before jumping to conclusions please read this list, this underline some important aspects:
+In this directory you can find some code to measure the performance of asm-dom. In particular you can find the results of asm-dom and [snabbdom](https://github.com/snabbdom/snabbdom), this allows you to make a comparison between the performance of asm-dom and a js virtual DOM. Before jumping to conclusions please read this list, this underline some important aspects:
 
-- asm-dom aims to let you write high perfomance web apps in C++. Your code will be compiled into WebAssembly, this means that it will run until 4 times faster (you can see that in the second test). However asm-dom needs to update the DOM and unfortunately, at the moment, this involves javascript. This means that the internals of asm-dom will call js for you and they will deal with the overhead of the binding between JS and WASM. In the future, without these bindings, asm-dom will be even more powerful. You have to be aware that, for the reason that we have just explained, **the results that you will see later won't represent the performance of your entire app, your code, your algorithms and so on will be a lot faster than this (they will be like the second test). asm-dom will be the only place that will deal with the overhead of the js <-> wasm communication.** 
+- asm-dom aims to let you write high perfomance web apps in C++ that will be compiled into WebAssembly. This means that they will run until 4 times faster. However asm-dom needs to update the DOM and unfortunately, at the moment, this involves javascript. So, the internals of asm-dom will call js for you and they will deal with the overhead of the binding between JS and WASM. In the future, without these bindings, asm-dom will be even more powerful, however, you have to be aware that, for this reason, **the results that you will see later won't represent the performance of your entire app, your code, your algorithms and so on will be a lot faster (they will be like the second test where there are no js calls). asm-dom will be the only place that will deal with the overhead of the js <-> wasm communication.**
 
-- asm-dom does not leave garbage after the execution of its tests, while snabbdom might leave some garbage that need to be collected by the garbage collector
+- asm-dom does not leave garbage after the execution of its tests, while snabbdom might leave some garbage that need to be collected by the garbage collector.
 
 There are 4 tests at the moment:
 

docs/cpp.md

@@ -105,7 +105,7 @@ int main() {
 
 In order to use asm-dom you have to prepare your js and C++ environment.
 
-To do this, **before importing your compiled code from C++** (wasm or asmjs) you have to include our js file: 
+To do this, as first thing, **before importing your compiled code from C++** (wasm or asmjs) you have to include our js file: 
 
 - if you are not using [npm](https://www.npmjs.com/package/asm-dom) you can import [our js file](https://github.com/mbasso/asm-dom/blob/master/dist/cpp/asm-dom.js) from [unpkg](https://unpkg.com/asm-dom/dist/cpp/asm-dom.js)
 
@@ -144,13 +144,24 @@ To do this, **before importing your compiled code from C++** (wasm or asmjs) you
   },
   ```
 
-You can now build your app using the source code in the [cpp](https://github.com/mbasso/asm-dom/tree/master/cpp) folder:
+After that, you can build your app using the source code in the [cpp](https://github.com/mbasso/asm-dom/tree/master/cpp) folder:
 
 - `asm-dom.hpp`
 - `asm-dom.cpp` or `asm-dom.a`
 
-To compile your code you can now use [emscripten (emcc cli)](http://kripken.github.io/emscripten-site/), [here](http://webassembly.org/getting-started/developers-guide/) is the installation guide. Please make sure to use the `--bind` option during the compilation, otherwise asm-dom will not work. You can find an example that uses all the optiminazionts [here](https://github.com/mbasso/asm-dom/tree/master/examples/todomvc%20-%20cpp/package.json).
-You can also notice that we are using 2 extra files with emcc `--pre-js` (`prefix.js`) and `--post-js` (`postfix.js`). These files allow us to import the generated js as a module with the `import` syntax as shown [here](https://github.com/mbasso/asm-dom/tree/master/examples/todomvc%20-%20cpp/src/index.js).
+and compile it using [emscripten (emcc cli)](http://kripken.github.io/emscripten-site/), [here](http://webassembly.org/getting-started/developers-guide/) is the installation guide. A few tips about this step:
+
+- please make sure to use the `--bind` option during the compilation, otherwise asm-dom will not work.
+
+- emcc has a lot of settings that can optimize the build, we suggest you to see [this](https://kripken.github.io/emscripten-site/docs/optimizing/Optimizing-Code.html) page and [our configuration]((https://github.com/mbasso/asm-dom/tree/master/examples/todomvc%20-%20cpp/package.json)) in the TODOMVC example.
+
+- we suggest you to compile your app to `.bc` and then use it to produce a WebAssembly version and an asm.js version that you can use as fallback
+
+After the compilation you can import your app:
+
+- if you are using webpack, you can see our [example]((https://github.com/mbasso/asm-dom/tree/master/examples/todomvc%20-%20cpp/src/index.js)). In order to import it as a module we have used 2 extra files with emcc `--pre-js` (`prefix.js`) and `--post-js` (`postfix.js`).
+
+- If you want to use wasm without webpack, you can see [this](https://gist.github.com/kripken/59c67556dc03bb6d57052fedef1e61ab) gist.
 
 If you are using [babel](https://babeljs.io/), please make sure to ignore the compiled files, the prefix and suffix: