--- a/hicBuildMatrix.xml	Mon Nov 27 08:38:04 2017 -0500
+++ b/hicBuildMatrix.xml	Sat Dec 16 16:26:37 2017 -0500
@@ -1,5 +1,5 @@
 <tool id="hicexplorer_hicbuildmatrix" name="@BINARY@" version="@WRAPPER_VERSION@.0">
-    <description>creates a matrix of interactions</description>
+    <description>creates a contact matrix</description>
     <macros>
         <token name="@BINARY@">hicBuildMatrix</token>
         <import>macros.xml</import>
@@ -134,9 +134,77 @@
     </tests>
     <help><![CDATA[
 
-**What it does**
+Creation of the contact matrix
+===============================
+
+``hicBuildMatrix`` creates a contact matrix based on Hi-C read pairs. It requires two sam or bam files 
+corresponding to the first and second mates of the paired-end H-C reads. The sam and bam files should
+ not be sorted by position. There are two main options to create the Hi-C contact matrix, either by 
+fixed bin size (eg. 10.000 bp) or by bins of variable restriction fragment size length. 
+``hicBuildMatrix`` generates a quality control output that can be used to analyze the quality of the Hi-C reads.
+
+Input
+-----
+
+`hicBuildMatrix` is having the following parameters:
+
+Parameters
+__________
+
+
+- two input BAM/SAM files
+- a bin size
+- a restriction cut file as an alternative to the bin size
+- restriction sequence: e.g. HindIII: GATC
+
+
+
+Output
+------
+
+`hicBuildMatrix` creates as an output:
+    - the contact matrix
+    - a bam file with the accepted alignments
+    - a quality report.
 
-Creates a matrix of interactions.
+Example plot
+-----------------------------------------------------------------
+.. image:: $PATH_TO_IMAGES/SRR027956.svg
+   :width: 70%
+
+Contact matrix created with `hicPlotMatrix`.
+
+Quality report
+--------------
+
+The quality report gives you information about:
+
+- how many pairs were used to build the contact matrix
+- dangling end pairs: These are reads that start with the restriction site and constitute reads that were digested but no ligated.
+- same fragment pairs: These are read mates, facing inward, separated by up to 800 bp that do not have a restriction enzyme in between. These read pairs are not valid Hi-C pairs.
+- self circles: Self circles are defined as pairs within 25kb with 'outward' read orientation
+- self ligations: These are read pairs with a restriction site in between that are within 800 bp.
+
+Contact distance:
+_________________
+- inter chromosomal
+- short range < 20 kb
+- long range
+
+Read orientation:
+_________________
+- inward pairs
+- outward pairs
+- left pairs
+- right pairs 
+
+.. image:: $PATH_TO_IMAGES/hicQC.png
+   :width: 70 %
+
+| For more information about HiCExplorer please consider our documentation on readthedocs.io_.
+
+.. _readthedocs.io: http://hicexplorer.readthedocs.io/en/latest/index.html
+
 
 ]]></help>
     <expand macro="citations" />