improve documentation and add code comments

[kdabir]

Let alone new contributors, even for myself when looking at the project after an year or so, it is very difficult to understand what the specific section of the script does.

• Create a CONTRIBUTING.md
• annotate tricky sections of code with comments
• Create simple how to's, eg:
  • how to add a new tool,
  • how to update tests