diff --git a/libs/freetdm/conf/freetdm.conf b/libs/freetdm/conf/freetdm.conf
index 1ea1a9f62a..bbaf1e3687 100644
--- a/libs/freetdm/conf/freetdm.conf
+++ b/libs/freetdm/conf/freetdm.conf
@@ -1,19 +1,47 @@
-[span wanpipe]
-name => FreeTDM
-number => 1
+; !! THIS IS A SAMPLE CONFIGURATION ONLY !!
+
+; refer to http://wiki.freeswitch.org/wiki/FreeTDM for further documentation
+
+[general]
+; whether to launch a thread for CPU usage monitoring
+cpu_monitor => no
+
+; How often (in milliseconds) monitor CPU usage 
+cpu_monitoring_interval => 1000
+
+; At what CPU percentage raise a CPU alarm
+cpu_set_alarm_threshold => 80
+
+; At what CPU percentage stop the CPU alarm
+cpu_reset_alarm_threshold => 70
+
+; Which action to take when the CPU alarm is raised
+; it can be warn and/or reject calls
+; cpu_alarm_action => warn,reject
+cpu_alarm_action => warn
+
+; spans are defined with [span <span type> <span name>]
+; the span type can either be zt, wanpipe or pika
+; the span name can be any unique string
+[span wanpipe myWanpipe]
+
+; valid trunk types are: FXO, FXS, EM, E1, T1, J1, BRI, BRI_PTMP
+trunk_type => FXS
+
+; add FXS channels from 3 to 4 at wanpipe span 1 to this freetdm span
 fxs-channel => 1:3-4
 
-[span wanpipe]
+[span wanpipe myWanpipe2]
+trunk_type => FXO
+; This number will be used as DNIS for FXO devices
 fxo-channel => 1:1-2
 
-[span zt]
-name => FreeTDM
-number => 2
+[span zt myZaptelSpan]
+number => 9999
 fxs-channel => 1
 
-[span zt]
-name => FreeTDM
+[span zt mySecondZaptelSpan]
+; This number will be used as DNIS for FXO devices
 number => 2
 fxo-channel => 3
 
-
diff --git a/libs/freetdm/conf/freetdm.conf.xml b/libs/freetdm/conf/freetdm.conf.xml
index 69bf99a0a0..986074dffb 100644
--- a/libs/freetdm/conf/freetdm.conf.xml
+++ b/libs/freetdm/conf/freetdm.conf.xml
@@ -1,3 +1,5 @@
+<!-- Please refer to http://wiki.freeswitch.org/wiki/FreeTDM for further documentation  -->
+
 <configuration name="freetdm.conf" description="FreeTDM Configuration">
   <settings>
     <param name="debug" value="0"/>
@@ -5,6 +7,8 @@
     <!--<param name="enable-analog-option" value="call-swap"/>-->
     <!--<param name="enable-analog-option" value="3-way"/>-->
   </settings>
+
+  <!-- use the <pri_spans> tag for native ISDN support (most likely broken at this point, check sangoma_pri_spans or libpri_spans for alternatives) -->
    <pri_spans>
      <span name="PRI_1">
        <!-- Log Levels: none, alert, crit, err, warning, notice, info, debug -->
@@ -24,9 +28,11 @@
        <param name="context" value="default"/>
      </span>
    </pri_spans>
-  <!-- one entry here per openzap span -->
+
+
+  <!-- Analog spans go here -->
   <analog_spans>
-    <span id="1">
+    <span name="myAnalog">
       <!--<param name="hold-music" value="$${moh_uri}"/>-->
       <!--<param name="enable-analog-option" value="call-swap"/>-->
       <!--<param name="enable-analog-option" value="3-way"/>-->
@@ -42,4 +48,5 @@
       <!--<param name="fail-dial-regex" value="^5"/>-->
     </span>
   </analog_spans>
+
 </configuration>
diff --git a/libs/freetdm/conf/pika.conf b/libs/freetdm/conf/pika.conf
index 8cc8d9c11d..78e095205e 100644
--- a/libs/freetdm/conf/pika.conf
+++ b/libs/freetdm/conf/pika.conf
@@ -1,3 +1,5 @@
+; you dont need this file unless you use PIKA boards
+
 ; each category is a config profile
 ; to apply the profile append it to a channel def in
 ; openzap.conf with @<profile_name>
diff --git a/libs/freetdm/conf/tones.conf b/libs/freetdm/conf/tones.conf
index 36db1d4d91..155b5fe17e 100644
--- a/libs/freetdm/conf/tones.conf
+++ b/libs/freetdm/conf/tones.conf
@@ -1,3 +1,5 @@
+; This file is used to generate telephony tones by FreeTDM
+
 [us]
 generate-dial => v=-7;%(1000,0,350,440)
 detect-dial => 350,440