--- a/docs/usage/performance.rst	Sun Sep 02 20:32:19 2012 +0200
+++ b/docs/usage/performance.rst	Sun Sep 02 20:53:09 2012 +0200
@@ -4,6 +4,17 @@
 Optimizing RhodeCode Performance
 ================================
 
+When serving large amount of big repositories RhodeCode can start
+performing slower than expected. Because of demanding nature of handling large
+amount of data from version control systems here are some tips how to get
+the best performance.
+
+* RhodeCode will perform better on machines with faster disks (SSD/SAN). It's
+  more important to have faster disk than faster CPU.
+
+* Slowness on initial page can be easily fixed by grouping repositories, and/or
+  increasing cache size (see below)
+
 
 Follow these few steps to improve performance of RhodeCode system.
 
@@ -18,7 +29,8 @@
     few hundreds of repositories on main page can sometimes make the system
     to behave slow when cache expires for all of them. Increasing `expire`
     option to day (86400) or a week (604800) will improve general response
-    times for the main page
+    times for the main page. RhodeCode has an intelligent cache expiration
+    system and it will expire cache for repositories that had been changed.
 
 2. Switch from sqlite to postgres or mysql
     
@@ -28,7 +40,6 @@
     performance increase.
     
 3. Scale RhodeCode horizontally
-    
 
     - running two or more instances on the same server can speed up things a lot
     - load balance using round robin or ip hash