The affiliation plugin is known to often fail when using its default configuration of "flag any authors with email domains not matching Orgs.kdl". For new users of Hipcheck, why these authors were flagged is not well-explained at all, the standard error output saying that they were "affiliated" but not providing any explanation as to what that means. For intermediate Hipcheck users, the documentation around what the Affiliation "strategy" and "mode" means and how to tailor the strategy / config file to their needs is very underdeveloped. In all, this makes the analysis difficult to understand and change, and I expect it will often be ignored or disabled quickly by users.
I recommend the following:
- Improve the language around the "modes" (Independent, affiliated, etc.) in both the code comments and documentation. In the docs, give toy config examples for achieving different sample config goals (how to use a strategy tree to allow one author but not another).
- I would also suggest renaming the modes to be more clear, perhaps "independent"/"affiliated" should just be "allow"/"deny".
- Revise how affiliate analysis is printed in the Hipcheck output to include some description of the strategy/mode config that was used so that new users can interpret the list of flagged authors.
The affiliation plugin is known to often fail when using its default configuration of "flag any authors with email domains not matching Orgs.kdl". For new users of Hipcheck, why these authors were flagged is not well-explained at all, the standard error output saying that they were "affiliated" but not providing any explanation as to what that means. For intermediate Hipcheck users, the documentation around what the Affiliation "strategy" and "mode" means and how to tailor the strategy / config file to their needs is very underdeveloped. In all, this makes the analysis difficult to understand and change, and I expect it will often be ignored or disabled quickly by users.
I recommend the following: