Try out new `Advanced Usage` intro/instructions in the WGCNA example
cansavvy opened this issue · comments
Background
Initially we had a discussion that sprung up on #353 (comment) (the first draft for a first "advanced topic").
The question is how should the instruction in the "advanced topic" section differ from the "non-advanced" topic sections (microarray and rna-seq).
Questions for discussion
Before we write more Advanced topic examples we should have some discussions, post some thoughts about how this section's material may need to differ from the non-advanced topics.
Some more specific questions (these can/should be broken into their own issues if we find that useful).
How might "Advanced Topics" users be different (or the same) from non-advanced topics users?
I think we should not assume an "advanced topic" user has necessarily gone through any non-advanced topic examples. Although some users may start out in a microarray or rna-seq section example, others (think about when we may have API examples #139 -- I don't think those will be the same kind of users as other advanced topics like WGCNA).
What material from our template example does or does not apply?
Will a separate advanced topics template be helpful or will things be too varied for a template to really help? (We may not know this entirely until we try out the first few examples).
I think the general content of Using a different refine.bio dataset with this analysis? section will need to be changed for most Advanced topics examples. Instead of instructing users about how to change file paths, we may need to give more instruction about what kinds of datasets are suitable for this analysis and what parameters/other items may need a closer look when switching datasets.
Technology isn't a known
We will not be able to assume a technology (rna-seq/microarray) so we may have to have tech-specific notes where applicable and definitely need to be clear when we are making tech specific moves.
Less hand-holding steps?
We should probably be careful with this one, I would still want to ere on the side of giiving more info than less, but this is a very context specific question. My guess is there are probably less times in these sections where we need to do a step like head(df) for example. I think prompts for users to "look at their data" can decrease.
More interpretation?
@jashapiro mentioned more "Why" and less "How". We should be able to trust users to do a tad more tailoring and troubleshooting at this point, but they may want more guidance about interpretation of results.
Related to these questions: When something isn't in R, we should figure out a new format that is as parallel as possible #139 (consistency is good).
Is there a particular timeframe for this issue?
If people can post their thoughts/responses to this, this sprint and next sprint then it would be good to get this somewhat aired out before we venture into writing more Advanced topics examples.
To clarify, not less "how", but more "why" (which will decrease the proportion of "how", but not the absolute amount!) The thought is that as we get into advanced topics, people need to know how to decide if an advanced method is appropriate for their analysis as much as how to implement it.
I've changed the title to reflect the new scope discussed via Slack. I filed to #372 for creating a second template for advanced usage examples.