update docs content adding a rationale