improve guide readability (and align with api doc)