EM JOSE Review - General comments

[e-marshall]

• As mentioned, there is a ton of great content that will be very helpful to users, but I think at times the cognitive load may be high. I think there are some small changes like having consistent page structures, more internal linking and using text formatting features like tabs that would greatly help the user experience.
  Some specific comments are:
• Would it be possible to make the numbered points in the overview section of each page link to the corresponding section further down on the page? I think this would help the readability of the content and make it easier to navigate.
• Sometimes general concepts/terms have external links in-text (eg. version control) and sometimes they don't. I think it would be helpful to have more linking for domain-specific terms that haven't already been defined on a given page throughout the book

below are more nits/suggestions, feel free to disregard them:
Overview sections

• in the Getting started with Github pages, 'overview' is followed by a colon, in Getting Started with Python and Getting Started with Jupyter its not

What's next sections

• Sometimes a sub-section of 'Summary' and sometimes not.

Time to learn sections

• I think its great that the pages have these, but visually, it looks like they are in the 'prereqs' section, which seems a little out of place
• It is a bit confusing for pages/sections with nested subsections
  • ex. Installing and Running Python
    • this says time to learn is 20 minutes, however it shows 3 sub-pages on the nav bar which each also show 20 minutes
    • if there are nested structures like this, it would be helpful if the time to learn estimate on the outer page encompassed the inner pages as well
    • Getting Started with Jupyter is another example of this
• Could you add a section-level time estimate for Getting Started with GitHub like there is for the python and jupyter sections?

Reference / Additional resource sections

• Some pages have a 'References' section, some have 'Resources and References', some have 'Additional Resources' that has a 'References' sub-section, I think having consistent naming for these sections would be cleaner
  • For example, in the Foundations section, reference pages tend to link to documentation while in the Core Sci. packages section, references sections contain formatted, peer-reviewed references and/or documentation. I personally like the structure used in the majority of the package-specific tutorials (like the pandas tutorial) where there is an 'additional resources' and a 'references' section, but defer to you on the best way to handle this.

Glossaries

• It's a bit confusing that only some pages have glossaries (here and here). Could you possibly pull out the page-specific glossaries into one page, with different sections, if needed, and potentially add more relevant terms?

[kafitzgerald]

Thanks for these suggestions.

I'll plan to take on the reference / additional resources (holding off on this) and glossaries portions of this along with #569 using the MyST glossary functionality unless folks have other ideas or concerns about that approach.