resolve issue 180 via better documentation