Enhanced Organization and Utility of Example Scripts

[gmhhope]

The current examples are relatively scattered, lacking easy starting points to guide user with a clear information flow.

It would be really helpful if basic bash workflow serves as the departure point and then point to different routes that are accompanied by examples used in manuscript and other scenarios, so that users could easily understand each particular way of running the pfpcm.

Thanks, MG

[jmmitc06]

Can you provide some more detail on this suggestion?

For instance, when you say the examples are scattered, do you mean that you cannot follow the workflows or that they are hard to find in the repo? They are all in one directory so I'm not sure how to make that more clear but if it is unclear what the workflows are for then that can be addressed.

Second, I'm not sure what you mean by "different routes"? Are you referring to the downstream data analysis or the actual pipeline processing? Are you suggesting merging the workflows with the analysis notebooks? Do you need more heavily commented and documented workflows or something else?

[gmhhope]

if it is unclear what the workflows are for then that can be addressed. Yes, this is what I meant, the information flow is important when there are multiple examples. Think about a train, everybody could have different endpoints that they want to arrive. You need to give them a departure station and then give them options to go, that is what I meant the information flow.

For example, a minimum script, a script go for just MS1 analysis and a more comprehensive one that encompassed every steps. Then you have a generic script and points to an example that basically use the generic script with a real-world example. With this navigation, it would significantly help reviewers/users to understand each utils, particularly speaking to the users who are not very familiar with metabolomics but want to tap on it.

Just my 2 cents.

Are you suggesting merging the workflows with the analysis notebooks?

No need for this. Just try to see a way to immediately engage the users rather than giving too much details right away. I would suggest that you try to give some meticulously detailed comments on the simple bash script, but relatively simple comments on the complex script. So these two examples of extremes could become very instructive but also not overwhelmed.

Best, MG

[jmmitc06]

There is a minimal workflow already that is what you are describing, but I can add an example of its usage if that would make it more clear along with comments.

[gmhhope]

Exactly. I saw your minimal workflow & complex one and the MS1 too. But I need my guest to understand their utils instead of clear description and navigation starting point to go to them.

What I meant is just to guide the users esp. those who don't know much about github and that, would significantly enhance your packages' user pools.

[gmhhope]

BTW, the front-page README could scare users right away. Try to set up a separate one with all the details. But keep a relatively succinct one at the "front door".

[jmmitc06]

I disagree with the previous statement as I feel it is based on the assumption that the tool should be usable without understanding how it works. I think users should understand the tool and what each step does if they are going to use it.

I'm fine with adding a quick start section to help people become familiar with the tool but if someone feels put off by the documentation being too long is very much, in my opinion, a first-world problem. The alternative is having less detail in the readme thereby forcing people to have to go out of their way to find the description of each step and what it does or having people use it without understanding it. In the end, if people use the tool without understanding how it works, they will make mistakes that will cause them to get nonsensical results.

[gmhhope]

It is completely your decision. It is only my 2 cents. You can drop it or pick it. No worry.