Add 2020 ux docs

[nlhkabu]

Preview
https://pip--10133.org.readthedocs.build/en/10133/ux-research-design/

TODO

• Cleanup markdown
• Ensure all links are working and point to the right place
• Make sure images and working, including alt-text

[pradyunsg]

YAY! I'm very happy to see this! ^>^

[pradyunsg]

Please make sure to also update docs/html/index.md. It currently references ux_research_design which should be updated to ux_research_design/index.

Further, you might want to a "toctree" similar to that page, listing all the sub-documents, if you want them to show up in the sidebar.

[nlhkabu]

ok, thanks @pradyunsg, will do.
I wasn't clear if it should be ux_research_design/index or ux-research-design/index?
The folder is ux-research-design should I change it to ux_research_design ?

[pradyunsg]

Ah, I didn't notice.

ux_research_design/index or ux-research-design/index

It just needs to match the folder name. We can use this opportunity to clean up the folder name -- we should setup a redirect from the underscore based name to the dashed name -- I can do that in a follow up.

The folder is ux-research-design should I change it to ux_research_design ?

Nah. The main benefit would be that the URL is preserved, but I don't think we care that much, given that adding a redirect is cheap.

[pradyunsg]

(editted the last comment extensively, in case someone's following via email)

[nlhkabu]

@pradyunsg are you able to point me in the right direction:
I have several pages that are not exposed in the menu, but sit in the '2020-research-outputs' folder.
I want to link to them from the html tables in research-results.md - see https://pip--10133.org.readthedocs.build/en/10133/ux-research-design/research-results/#research-results
I am having trouble working out what the URLs should be, or how to reference them correctly. Do you know how I can do this? Thanks!

[pradyunsg]

I am having trouble working out what the URLs should be, or how to reference them correctly.

The way I would reference them is to use Markdown links + make this a Markdown table; but I trust your judgement on whether that's better. I think [About our users](2020-research-outputs/about-our-users) should generate the correct link.

The other option would be to change the URL we're using in the a[href] tags:

-<a href="2020-research-outputs/override-conflicting-dependencies">
+<a href="../2020-research-outputs/override-conflicting-dependencies">

I haven't tested either of these though -- I am speaking based off of my understanding of how Sphinx's linking logic / output generation works.

[pradyunsg]

If you're wondering what the CI failures are, those are due to trailing whitespace in a bunch of these files: https://github.com/pypa/pip/runs/3128618975#step:4:59

[nlhkabu]

Thanks @pradyunsg - I have cleaned up the hyperlinks as suggested.
re: whitespace - I am still to work through a number of the files in /2020-research-outputs - some were written in Google Docs and have been exported to .md and will need a lot of cleanup!

[pradyunsg]

I have several pages that are not exposed in the menu, but sit in the '2020-research-outputs' folder.

The sidebar is populated by the {toctree} code blocks. Basically, to have the files show up in the sidebar, you'd need to include them in one of those blocks.

What I would suggest doing is adding the following wherever you want in the research-results.md

```{toctree}
:hidden:

2020-research-outputs/about-our-users
2020-research-outputs/ci-cd
2020-research-outputs/improving-pips-documentation
2020-research-outputs/mental-models
2020-research-outputs/override-conflicting-dependencies
2020-research-outputs/personas
2020-research-outputs/pip-force-reinstall
2020-research-outputs/pip-logo
2020-research-outputs/pip-search
2020-research-outputs/pip-upgrade-conflict
2020-research-outputs/prioritizing-features
2020-research-outputs/users-and-security
```

These are relative paths, you can optionally include .md in them as well.

I think you can probably remove the :hidden: and use this as a substitute for the table, if you think just a list with the page titles is enough. :)

[pradyunsg]

If you wanna know more details about the whole {toctree} thing, you can find them under "Table of Contents" here: https://www.jetbrains.com/pycharm/guide/tutorials/sphinx_sites/more_authoring/

(Jetbrains didn't include anchors in headings 🤷🏽‍♂️)

[nlhkabu]

Thanks @pradyunsg - Links are now working...
I don't actually want the results pages to display in the menu - and prefer the table structure to a TOC.

Question: do we have any preference of where we want to host images? Right now I have some on GitHub and others on imgur.com

[pradyunsg]

I don't actually want the results pages to display in the menu

Ah, whoops, I misunderstood. :)

do we have any preference of where we want to host images?

Nope!

[brainwane]

I'd love to get this merged.

@ei8fdb do you have links for any of the user experience trainings that we did in late 2020 and early 2021? I would very much like to include those here. I'm sorry I'm late in asking for them.

[nlhkabu]

Closing this and making a new PR at #10745, as I accidentally made a branch instead of a fork :)

[nlhkabu]

@pradyunsg would you be able to remove this branch for me? Thx

[pradyunsg]

Done! :)