docs + explinations + minor adjustments