api: improving conceptual docs