improved markdown and explanations