updated doc - WIP + refactoring