DOC/MAINT: addressing @jairideout's comments