Update docs to make it more beginner friendly

[monicayao]

Summary

The documentation as of now has a couple of parts that could be updated to become friendlier for contributors that are just starting out with tedana. In particular, some terms and explanations could be flushed out a bit more (definition, more information, etc). And the first page could redirect the users to pages that are relevant to the information they are looking for.

Additional Detail

In the homepage, I think it is helpful to refer users to either the 'Multi-echo fMRI' or 'Processing pipeline details' pages depending on what they want to learn more about tedana. In particular, if they want to learn more about the multi-echo fMRI technology, they should visit 'Multi-echo fMRI' and if they want to learn more about how tedana is analyzing the data, they should visit 'Processing pipeline details.' Right now there is a 'Content' section, but I think that the above information could go well in the 'About' section.

In both 'Multi-echo fMRI' and 'Processing pipeline details,' there are a few acronyms that are introduced early on, but not explained until either later or not at all. I think it would be good to expect the people who refer to that docs to refer to them out of order, so each page should expand on the acronym without assuming that the reader already knows the acronym from another page. For example, on 'Processing pipeline details,' the BOLD acronym is used, but it was explained in 'Multi-echo fMRI.'

For the 'Processing pipeline details' page, PCA and ICA are referred to in the beginning, but not explained until the later bullet points. Even then, it would be good to have a short 1 sentence summary about the PCA and ICA steps before big sections TEDPCA and TEDICA to give the readers a sense of where everything is going.

In addition, the 'Processing pipeline details' could use some restructuring, in making the image and the section match (though it is quite organized right now). While making these changes, I will also try to add links to the page to prepare for the upcoming Hackathon.

This is just my perspective as someone who is just starting to read the docs for tedana! I will work on this for the next week, please assign me to this issue 😸

Next Steps

• Edit the homepage to redirect users
• Make additions to some sections in 'Multi-echo fMRI' (Make additions to ME MRI, why ME, and Sequences sections, which will add clarity)
• Make changes to 'Processing pipeline details' to explain all acronym, make sure that the page is readable independently
• Make changes to 'Processing pipeline details' by adding more details to steps before sections to ensure a better logical flow
• Link sections to code or relevant API page

[jbteves]

Hi @monicayao ! Thank you for submitting this issue. Could you clarify where you think it would be helpful to redirect users to?
Additionally, would you mind expanding on which details in "Multi-echo fMRI" and "Processing pipeline details pages" you found confusing?
Thank you!

[monicayao]

Hi @monicayao ! Thank you for submitting this issue. Could you clarify where you think it would be helpful to redirect users to?
Additionally, would you mind expanding on which details in "Multi-echo fMRI" and "Processing pipeline details pages" you found confusing?
Thank you!

@jbteves Sure! I will make edits to my issue 👍

[jbteves]

@monicayao thanks for adding the documentation label in the title, but typically we add it with the colored labels to the on the right side of the tab. I'll do so now; that's a good reminder for me.
Additionally, could you add some of that elaboration into your next steps? Basically what I would ask you to do from here is to open up Pull Requests addressing those next steps, and have you mark them complete as you have PRs opened to address them. It's very helpful to have those next steps reflect the pull requests that will follow.
@emdupre @tsalo WDYT about the proposed changes?

[monicayao]

Additionally, could you add some of that elaboration into your next steps? Basically what I would ask you to do from here is to open up Pull Requests addressing those next steps, and have you mark them complete as you have PRs opened to address them. It's very helpful to have those next steps reflect the pull requests that will follow.

@jbteves done! Each of the steps are pretty small in my opinion. Looking forward to working on them this week 👍

[jbteves]

Excellent, thank you!

[KirstieJane]

Thank you @monicayao for opening up the issue! Good luck with the reading and processing of the guide! As @jbteves says, it’s really helpful for the other members of the community for you to open a pull request early so we can give you feedback and suggestions. (It’s also more fun and motivating that way!)

You may feel like you want the updates to be polished before you open the PR, but try not to let perfection be the enemy of the good. As we said in the meeting yesterday - you could spend the whole summer trying to understand ME-fMRI 😂🤣😫

Thanks again! Really appreciate the work 💖

[emdupre]

@dowdlelt is this also being addressed in #419 ?

[dowdlelt]

I think so - I've just finished added links to relevant sections of the API page on the approach, and I did a large amount of cleaning on the tedana pipeline page. So I think its mostly good to go. I want to do a another read through once we've made it through all the hackathon business.

[emdupre]

@dowdlelt @mvaziri @monicayao -- with the merge of #419 I think we've made a lot of progress on this ! I think this issue is ready to close, but I'd love another read-through from y'all for your thoughts ✨

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions to tedana:tada: !

[jbteves]

I vote we go ahead and close this, WDYT @emdupre @dowdlelt ?

[stale]

This issue has been automatically marked as stale because it has not had any activity in 90 days. It will be closed in 600 days if no further activity occurs. Thank you for your contributions to tedana:tada: !

[tsalo]

Given the consensus on closing from 90 days ago and the fact that the issue is stale once again, I'm going to close this now.