Migration guide for workflow outputs #6162
Conversation
Signed-off-by: Ben Sherman <[email protected]>
✅ Deploy Preview for nextflow-docs-staging ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
There was a problem hiding this comment.
I've suggested headings to the bullet points as I think it's easier to scan.
Before making suggestion to the example migration, did you want it to be follow along? Or something more demonstration with explanations?
This will impact some of the language:
"Declare an output for each channel..." vs "An output channel for each must be declared..."
Signed-off-by: Ben Sherman <[email protected]>
|
Thanks Chris, all great improvements It is mostly a follow-along, with some explanation sprinkled throughout. I need to guide the reader through a specific example while also pausing at times to make more general points. The current version is my best attempt to balance these things |
|
Great. The steps you have included are already great, so I'll make suggestions that tweak the language to make it consistent as a follow-along. |
|
From our discussion last week, we will follow up this PR with a separate tutorial about the rnaseq-nf pipeline to give more context. Also, this guide is really more of a tutorial, but we already renamed the section from "Tutorials" to "Guides". Once we move to seqera docs, we should have explicit sections for both I also wouldn't be opposed to just having a "Guides" and "Tutorials" section in the current docs? I just didn't want to keep renaming the current section back and forth |
|
I agree with your points. Catching up on some backlog today and will review the current PR in the next day or so. |
There was a problem hiding this comment.
Sorry it took me so long to get to this.
I've added suggestions to make this an example of a migration. Past tense, "this is what was done to change this pipeline".
Some sections were multi-step, i.e., they showed something and then showed a better way of doing it, and then they switched to "you could do it this way, but it was done this way for these reasons."
Let me know what you think. Happy to keep iterating if you have suggestions.
Some of the suggestions got a little messy, so if you're happy and accept, I'll give it another check to make sure everything is consistent.
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
Signed-off-by: Ben Sherman <[email protected]>
|
I split the Guides section into Tutorials and Guides. Based on our previous discussion, this migration guide seems to be a "tutorial", since it is now a strict step-by-step guide, but also contains some explanations. Whereas I think your page on spot retries is the only guide in this list? I don't think the past-tense suggestions are a good fit for what I'm trying to do. It feels too brittle and distant, whereas the present-tense imperative feels more engaging and interactive. A similar approach is taken in the "tutorials" for data lineage and Flux, for similar reasons. So I would prefer to try to make it work with the current approach |
|
Fair enough, I'll revise. |
There was a problem hiding this comment.
It all looks good. I'll try and revisit the tutorials and guides again soon to add some standardization around language, but that will be a nit picking exercise that isn't urgent.
I don't want to hold this up anymore. A couple of minor working suggestions (ignore if you think the meaning is changed), otherwise good to go.
Signed-off-by: Chris Hakkaart <[email protected]>
Co-authored-by: Chris Hakkaart <[email protected]> Signed-off-by: Ben Sherman <[email protected]>
No description provided.