adding more docs about optional parameters and new output format