diff --git a/build_arm_image/01_create_sdcard.sh b/build_arm_image/01_create_sdcard.sh
index 687ba3f..513f43e 100755
--- a/build_arm_image/01_create_sdcard.sh
+++ b/build_arm_image/01_create_sdcard.sh
@@ -5,6 +5,8 @@
 # Usage:
 #  ./01_create_sdcard.sh downloaded_debian_image.zip /dev/sdcard_device
 #
+#
+# Status: functional
 # Licence: GPLv3
 # Author: sylvain303@github
 
@@ -46,7 +48,6 @@ skip_if() {
     return 1
 }
 
-
 sha_verify_zip() {
     local zip=$DEBIAN_IMG_ZIP
     local out=_build_arm_steps/sha_verify_zip
@@ -71,10 +72,10 @@ unzip_img() {
     DEBIAN_IMG=$(ls _build_arm_steps/ | grep \\.img$)
 }
 
-# helper try to guess top device name
+# helper, try to guess top device name
 # /dev/sdp2 => /dev/sdp
 # /dev/mmcblk0p1 => /dev/mmcblk0
-# just some regexp no smart thing
+# just some regexp, no smart thing
 get_top_device() {
     local device="$1"
     local regexp1='^/dev/sd[a-z]'
@@ -93,6 +94,7 @@ get_top_device() {
     echo "$device"
 }
 
+# helper, umount the sdcard partition if any
 umount_sdcard_partition() {
     [[ -z "$SDCARD" ]] && { echo '$SDCARD is empty refusing to run'; return; }
     local p
@@ -120,6 +122,7 @@ test_all_tools() {
     done
 }
 
+# mount the .img so we can write on it before copying on the sdcard
 mount_loopback_img() {
     [[ -z "$DEBIAN_IMG" ]] && { echo '$DEBIAN_IMG is empty refusing to run'; return; }
     mkdir -p _build_arm_steps/mnt
@@ -142,6 +145,7 @@ umount_loopback_img() {
 }
 
 # copy a local key for ssh without password later
+# having an ssh-key pair to remote connect on the raspi will be used by the next step
 add_ssh_key_to_img() {
     mount_loopback_img
     cd _build_arm_steps/mnt/home/pi/
@@ -202,5 +206,6 @@ then
     # pass positional argument as is
     main "$@"
 else
+    # just print STEPS so I can copy/paste to call them interactivly
     echo $STEPS
 fi
diff --git a/build_arm_image/02_install_yunohost.sh b/build_arm_image/02_install_yunohost.sh
index e13928a..ef587c9 100755
--- a/build_arm_image/02_install_yunohost.sh
+++ b/build_arm_image/02_install_yunohost.sh
@@ -2,21 +2,40 @@
 #
 # Usage: ./02_install_yunohost.sh DHCP_IP_ADDRESS_OF_RASPBERRYPI
 #
-# apply this doc: https://github.com/Sylvain304/doc/blob/master/build_arm_image.md
+# This script apply this doc: 
+# https://yunohost.org/#/build_arm_image
+#
+# Doc: See README.md
+#
+# STEPS:
+#  1. enlarge filesystem with raspi-config --expand-rootfs and reboot
+#  2. run install_yunohostv2 on the raspi
+#  3. install an yunohost-firstboot script and shutdown
 # 
 # Status: draft
 # Licence: GPLv3
 # Author: sylvain303@github
 
-# usefull wrapper to use ssh with our nopasskey
+# wrapper to use ssh with our nopasskey
+# Usage: sshpi "some remote commands"
 sshpi() {
     ssh -i _build_arm_steps/nopasskey pi@$PI_IP "$@"
 }
 
 # harcoded test IP
-PI_IP=192.168.1.50
+PI_IP=192.168.1.2
+# the installer script is used localy, no git clone else where.
 YUNOHOST_INSTALL=../install_yunohostv2
+# the folder on the raspberrypi, where script are uploaded
 YUNOHOST_REMOTE_DIR=/tmp/install_yunohost
+# dummy password
+PASSROOT='Free_money?yunomakeit'
+
+# wrapper to init with positional parameters
+init_param() {
+    PI_IP=$1
+    ask_root_pass
+}
 
 ask_root_pass() {
     echo "HINT: very good program to generate strong memorisable passwords: pwqgen"
@@ -46,9 +65,10 @@ scp_yunohost() {
         return 1
     fi
 
-    local script=$1
-    local scriptb=$(basename $script)
+    local script="$1"
+    local scriptb="$(basename $script)"
 
+    # no real scp, just wrap with sshpi
     cat "$script" | \
     sshpi "mkdir -p $YUNOHOST_REMOTE_DIR && \
         cat > $YUNOHOST_REMOTE_DIR/$scriptb && \
@@ -59,7 +79,7 @@ scp_yunohost() {
 # helper, compute common remote_step script name so they can be skiped by do_step
 make_step_file() {
     local step_name="$1"
-    local step_file=yuno_step_${step_name}.sh
+    local step_file="yuno_step_${step_name}.sh"
     echo $step_file
 }
 
@@ -68,14 +88,19 @@ make_step_file() {
 create_remote_script() {
     local step_file=$(make_step_file "$1")
     local actions="$2"
+    local dst="_build_arm_steps/$step_file"
 
-    echo '#!/bin/bash' > _build_arm_steps/$step_file
-    echo "$actions" >> _build_arm_steps/$step_file
-    scp_yunohost _build_arm_steps/$step_file
+    echo '#!/bin/bash' > $dst
+    echo "# $1" >> $dst
+    echo "$actions" >> $dst
+    scp_yunohost $dst
 
+    # the remote file on the raspi
     echo $YUNOHOST_REMOTE_DIR/$step_file
 }
 
+# ======================= ACTIONS - remote actions steps to be performed on the raspberrypi.
+
 init_sdcard_and_reboot() {
     local actions="
 # fix locale warning
@@ -83,6 +108,7 @@ sudo sed -i -e '/\(en_US\|fr_FR\)\.UTF-8/ s/^# //' /etc/locale.gen
 sudo locale-gen
 # enlarge filesystem, we need more space to install yunohost
 sudo raspi-config --expand-rootfs
+echo 'rebooting raspberrypi…'
 sudo reboot
 "
     create_remote_script $FUNCNAME "$actions"
@@ -92,10 +118,10 @@ install_yunohostv2_on_sdcard() {
     local actions="
 # change root password
 echo 'root:$PASSROOT' | sudo chpasswd
+# some packages
 sudo apt-get -y install git
-# so you can hack your local copy of install_yunohost over and over…
-# run yunohost installer unattended (scp previously with scp_yunohost_installer)
 cat << ENDMSG
+!!!!!!!!!!!!!!!!!!!!!!! sdcard builder !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 Launching unattended install_yunohostv2 which will take some time to run…
 You can watch using a new ssh connection to the raspberrypi.
 By example issuing those commands:
@@ -103,7 +129,9 @@ By example issuing those commands:
  source 02_install_yunohost.sh
  sshpi
  tail -f /var/log/yunohost-installation.log
+!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
 ENDMSG
+# run yunohost installer unattended (scp previously with scp_yunohost)
 cd /tmp/install_yunohost && sudo ./install_yunohostv2 -a
 "
     create_remote_script $FUNCNAME "$actions"
@@ -111,18 +139,25 @@ cd /tmp/install_yunohost && sudo ./install_yunohostv2 -a
 
 finalize_yunohost() {
     local actions="
+# uploaded modified or new config files to the raspberrypi
 cd /
-tar xzf $YUNOHOST_REMOTE_DIR/etc.tzg
-chmod a+x /etc/init.d/yunohost-firstboot
-insserv /etc/init.d/yunohost-firstboot
+sudo tar xzf $YUNOHOST_REMOTE_DIR/etc.tgz
+# yunohost-firstboot is an helper to cleanup and resizefs with srinked sdcard
+# image
+sudo chmod a+x /etc/init.d/yunohost-firstboot
+sudo insserv /etc/init.d/yunohost-firstboot
 cat << ENDMSG
+=================================================================================
 We are going to shutdown the raspberrypi now.
 When it's done, the yunohost image is ready to be copied back on your comupter.
 * Unplug raspberrypi
 * remove the sdcard
-* Go to next step
+* Go to next step!
+=================================================================================
 ENDMSG
-shutdown
+# remove pi user, we will not be able to ssh connect anymore
+# sudo userdel pi
+sudo shutdown -h now
 "
     create_remote_script $FUNCNAME "$actions"
 }
@@ -132,7 +167,10 @@ reboot_pi() {
     sshpi "sudo reboot"
 }
 
-# helper simply visualy wait for raspberrypi to come up for ssh
+# ======================= END ACTIONS
+
+# helper, simply visualy wait for raspberrypi to come up for ssh
+# Usage: wait_raspberrypi || some_fail command
 wait_raspberrypi() {
     local max=30
     local n=1
@@ -140,7 +178,9 @@ wait_raspberrypi() {
     while [[ $n -le $max ]]
     do
         sleep 1
-        output=$(timeout 2 ssh -i _build_arm_steps/nopasskey pi@$PI_IP 'echo up' 2> /dev/null)
+        # remove redirect to /dev/null to debug
+        output=$(timeout 2 ssh -o "StrictHostKeyChecking=no" \
+            -i _build_arm_steps/nopasskey pi@$PI_IP 'echo up' 2> /dev/null)
         echo -n .
         if [[ "$output" == 'up' ]]
         then
@@ -162,33 +202,42 @@ wait_raspberrypi() {
     fi
 }
 
+# wrapper, execute a step script on the raspberrypi or skip it
+# Status: draft
 do_step() {
     local step=$1
     local step_file=$(make_step_file $step)
     local remote_step
     echo -n "$step: "
+    # skip if script already there
     if [[ -e "_build_arm_steps/$step_file" ]]
     then
         echo "SKIPED"
+        return 1
     else
         echo "RUNING"
         remote_step=$(eval $step)
         sshpi $remote_step
+        return 0
     fi
 }
 
+# main script code, wrapped inside a function, so the whole script can also be
+# sourced as a lib, for debug or unittesting purpose.
 main() {
     do_step init_sdcard_and_reboot
 
     wait_raspberrypi || return 1
 
-    do_step install_yunohostv2_on_sdcard
+    scp_yunohost $YUNOHOST_INSTALL
+    NEED_REBOOT=false
+    do_step install_yunohostv2_on_sdcard && { NEED_REBOOT=true; }
 
-    # copy the installation.log on the PC
+    # backup the installation.log on the PC
     sshpi "cat /var/log/yunohost-installation.log" > \
         _build_arm_steps/yunohost-installation.log 
 
-    reboot_pi
+    $NEED_REBOOT && reboot_pi
 
     wait_raspberrypi || return 1
 
@@ -197,3 +246,11 @@ main() {
     scp_yunohost _build_arm_steps/etc.tgz
     do_step finalize_yunohost
 }
+
+# sourcing code detection, if code is sourced for debug purpose, main is not executed.
+[[ $0 != "$BASH_SOURCE" ]] && sourced=1 || sourced=0
+if  [[ $sourced -eq 0 ]]
+then
+    # pass positional argument as is
+    main "$@"
+fi
diff --git a/build_arm_image/README.md b/build_arm_image/README.md
index 31b1ffa..3872c88 100644
--- a/build_arm_image/README.md
+++ b/build_arm_image/README.md
@@ -1,10 +1,10 @@
 # Build your own yunohost image for Raspberry Pi
 
-This folder contains helper scripts to build an arm image for raspberry.
+This folder contains helper scripts to build an arm image of yunohost for raspberry.
 The files here are for builder. They are not needed to install your yunohost.
 
-The folder structure maps debian OS folders, shell script here are helpers.
-Files in subfolders will be copied on the sdcard when installation is finished.
+The folder etc/ structure maps debian OS folders, shell script here are helpers.
+Files in etc/ subfolders will be copied on the sdcard when installation is finished.
 
 ## License
 All the content here is distributed under [GPLv3](http://www.gnu.org/licenses/gpl-3.0.txt).
@@ -15,7 +15,18 @@ All the content here is distributed under [GPLv3](http://www.gnu.org/licenses/gp
 
 ## Files
 
-Descriptions of the files available here.
+Description of the files available here.
+
+All step stripts are using your PC to store some files in the folder _build_arm_steps/.  This folder will be created by 01_create_sdcard.sh. You can wipe it, or remove selected script data form it, to redo a step.
+
+All step script are designed to run in this folder:
+
+~~~
+git clone this_repos
+cd path_to/build_arm_image/
+~~~
+
+then run steps scripts in order.
 
 ### Run on PC
 
@@ -28,9 +39,9 @@ This script requier root privilege to run and modify the local sdcard image.
 
 #### 01_create_sdcard.sh
 
-Create a bootable image for raspbian. You have to download the .zip of the image.
+Create a bootable image for raspbian. You have to download the .zip of the raspbian image.
 It embeds sudo call for using dd to copy the raw image to the sdcard. 
-It will add an ssh key to pi default rasbian user in oder to connect later to continue automated installation. The pi user will be remonved at the end. The key-pair is generated only for you.
+It will add an ssh key to pi default rasbian user in oder to connect later to continue automated installation. The pi user will be removed at the end. The ssh key-pair is generated only for you.
 
 Usage:
 
@@ -38,7 +49,7 @@ Usage:
 ./01_create_sdcard.sh image_rasbian.zip /dev/device_to_sdcard
 ~~~
 
-It takes some minutes to perform all the steps. Be patient.
+It takes some minutes to perform all the steps (~ 2m3.867s at last run). Be patient.
 
 Use `df` or `lsblk` to find the name of your sdcard device. The script is taking care of umonting the partion if any. It also guess the disk's name if you give an partition's name instead of entire disk device's name.