[ENH] - Documentation enhancement

[SamGuay]

I like the new layout!

Here's a bunch of things I've noticed while browsing through it. Sorry for the long issue; I can split it into many issues if needed.

Accessibility / layout wise:

You can see the accessibility report here with errors and provided solutions. Some of the errors should be easy to fix:

• Contrast between orange (#FF6E42) and white (#FFF) doesn't meet accessibility standards. Here's a tool to help with picking colours that meet standards: https://accessible-colors.com/.
• Missing alt-text for some images.
• Other issues would need be open/fixed upstream in either portray or mkdocs since it is related to the structure per se (e.g., Empty form label, etc.).

README.md

Is it dcm2bids or Dcm2Bids? Just asking because the repo is Dcm2Bids 😅

Your friendly DICOM converter.

I feel dcm2bids is more than just a friendly DICOM converter, and it is already mentioned in the paragraph below how friendly it is. I suggest we remove this piece.

• Fix dead URL for Install dcm2bids in the documentation section.

• Fix weird URL for Follow the tutorial in the documentation section. It currently directs to https://unfmontreal.github.io/Dcm2Bids/tutorial, which doesn't look like a tutorial at all.

• Fix weird URL for Seek for more advanced usage in the documentation section

• I think changing the Issues title to Issues and Questions would help end-users not familiar with the concept of issues find more easily where to ask questions.

• Add direct link to Neurostars in the issue section (e.g. If you have a usage question, please post your issue on Neurostars with dcm2bids as an optional tag. The tag is really important because Neurostars will only notify us if the tag is present).

• Not everyone knows about Neurostars, so maybe adding a small paragraph (1-2 sentences) explaining what's the purpose and gently suggest to start by looking for similar issues at https://neurostars.org/tag/dcm2bids before posting their question. It could potentially reduce the burden on maintainers who answer similar questions many times.

• Fix weird URL for contributing guide in the issue section

Code of Conduct.md

• Erase /newline between Accordingly, and everyone in the first paragraph.
• Fix typo in nativa language
• Fix bullet points rendering in the Our standards section
• Fix bullet points rendering in the Enforcement section
• https://www.contributor-covenant.org/version/1/4/code-of-conduct.html doesn't appear as a URL for some reason?

contributing.md

• Fix :heart: emoji doesn't appear. Does portray render emoji?
• Fix URL for Create an issue, tag with labels and contribute at the top of the page.
• pop into this [thread](https://github.com/UNFmontreal/Dcm2Bids/issues) to introduce yourself! links to issues and not a specific thread.
• same as above: on the open issue [welcome][dcm2bids-welcome] doesn't work.
• Fix a bunch of links in the Contributing through GitHub section
• [scope][dcm2bids-scope] needs to be fixed as well in Create an issue.
• The all contributors bot is mentioned in the Recognizing your contribution section, but it has not been added yet. (This is good for another issue, not this one).
• Fix text emoji :wave::smiley:

1. Usage

• What does BIDS sidecar^1 (the exponent 1) mean in the Introduction section?
  • Realized in the next section that this footnote could fit on this page as well.
• I know some users who don't know what CLI means, so that I would put a more explicit section title.
• Change code to pull singularity image from the docker link directly? e.g., singularity pull dcm2bids_latest.sif docker://unfmontreal/dcm2bids:latest Maybe there is a reason why it is singularity build dcm2bids.sif containers/singularity.def right now, and I'm unaware of it.

2. Tutorial

• Fix broken URL for intendedFor in the Building the configuration file

Random

Can we change the favicon?

And that is it for now! The rest is more doc-related, so I'll likely open new issues when I have some free time.

---

ps: These are merely suggestions, and I am not strongly attached to any of them. Feel free to delete irrelevant ones.
pps: Happy to propose a first PR to deal with all of those

[morteza]

Since there is an ongoing task to develop a conda recipe, I'm not sure this is still relevant.

But installation instruction as explained in the docs/2-tutorial.md can be simplified. Conda interoperability with pip can install all the dependencies in one step; see the pip: blow:

name: dcm2bids
channels:
    - conda-forge
dependencies:
    - dcm2niix
    - pip
    - pip:
          - dcm2bids

It doesn't need another pip install.

[SamGuay]

Thanks @morteza for the pointer! For now, in #122 I changed the instruction for a pure install with conda since dcm2bids is now on conda-forge (#119).

However, I think in the long-term, we should also offer instruction for a pip only install, but that is for another issue.

Bonus: I didn't know we could do such a thing, so here's a personal thank you!

[SamGuay]

• Clarify installation section. As of now, pip install dcm2bids shouldn't appear since if we follow the doc, it would install dcm2bids twice - with conda and pip.

[SamGuay]

Much better with #162 - Closing this for now.