CEV v.3.0.0 User Guide (pre-release)

[whelena]

This discussion is to document beta-tester response on the updated user guide for CEV v.3.0.0.

Evaluation Criteria:

1. Technical clarity
   • Any jargon or statements that need further explanation?
   • Are the terminology consistent with the field?
   • Are the examples reproducible?
2. User experience
   • Is the guide well-organized (follows a logical flow) and easy to navigate?
   • Is the progression from simple to complex features makes sense?
   • Are there sufficient examples?
   • Are there any common troubleshooting scenarios I should include?
3. Completeness
   • Are all the key features documented? All the customizations, tree modes, etc.
   • Are the installation guide sufficient?

[WuSelina]

Scale of 1-5 with 1 = very poor and 5 = very good:
1. Technical clarity: 4 = good

• I thought this was appropriate for someone in the field (using CEV as intended) to understand

2. User experience: 2 = poor

• Overall, the guide is well-organized (flow) for a group of users in general
  • I am used to seeing the available options/arguments at the beginning, so I would have liked seeing the options for node aesthetics at the beginning or previewed at the beginning, like in BPG
• The progression from simple to complex features makes sense, so that is why I'm not sure if the node aesthetics and similar list of adjustable parameters should be moved/previewed earlier
• I experienced difficulty quickly identifying which parameters I should specify as a table (either the table for nodes or the table for text) or passed in SRCGrob() (e.g., label.cex, 'node.text.cex, colour.scheme`)
• Since node.size can be adjusted for each node, I thought the text identifying the node (label.cex) should also be adjustable for each node (could potentially be node.id.cex)
  • Also, I know it is difficult to distinguish label.cex and node.text.cex in parameter name as well as in description, but I have confused these arguments with each other a few times
• Gave this a lower rating while also considering the points in 'Completeness' section

3. Completeness: 3 = fine

• I think the installation guide is sufficient, but I also have a few months of experience using CEV (and asking how to use it) from the previous versions
• I think documentation can undergo some quick fixes still:
  • The node.id column is sometimes cut off in the guide
  • I think it is mostly just me, but it was not initially clear which palettes are available (or unavailable) to pass into 'colour.scheme' in SRCGrob()
  • I was trying to specify y-axis limits, which is not its own parameter, but can be done through yat = list()
  • I do not think it was clearly stated that neither spread nor angle appear to have an effect when CP is visualized

---

Additional Notes

• When plotting CP, neither spread nor angle appear to have an effect

• When NOT plotting CP,

  • In radial mode, spread does not appear to have an effect when there are only 2 children
  • In dendrogram mode, when both spread and angle are specified, angle appears to ‘take precedence’ (as in spread does not appear to have an effect), but I would not use angle in dendrogram mode
  • What will happen with use of spread and angle when in mixed mode?

• CCF works with dendrogram mode too -- not sure if this is intended/want to include in documentation

• I think it would be very helpful to at least have a top.padding parameter (but not high priority)

  • If title is included, there is a lot of white space on bottom. When decreasing the height, both top and bottom of the plot are cut off. When increasing the height, white space is added to the top AND bottom, resulting in longer (and smaller previewed) plots with a lot of empty space on the bottom