search

OSC / ood-documentation

Documentation for Open OnDemand generated using Sphinx
https://osc.github.io/ood-documentation/latest/
MIT License
8 stars 50 forks source link

tweak install instructions around inital setup #845

Closed johrstrom closed 11 months ago

johrstrom commented 1 year ago

Modify this link to include the branch name, and possibly the page this PR modifies:

https://osc.github.io/ood-documentation-test/ssl-install/

Reword this so that we reinforce that when it says you need to setup authentication - you really need to setup authentication.

Oglopf commented 1 year ago

Eh, I'm not sure. I want to walk through this because I'm a dev on this team, and yet just last week I ran into this and was baffled. Why? Because I'm being told to do 2 things at once in these instructions and I don't think that's the way to do it. Why not just not mention any of this, and instead once what they need is done with SSL, move on.

johrstrom commented 1 year ago

I don't follow what you're suggesting, feel free to open a different pull request.

johrstrom commented 1 year ago

And 🤦‍♂️ I thought I'd merged #842, but apparently I didn't so that's an option as well.

Oglopf commented 1 year ago

I think I see the confusion. Look how the sidebar is navigating through the install, yet when it gets the end of the page and mentions auth and securing httpd, those two things are then split out from the install steps (auth is not even a step numbered step, but it's own subsection).

So, we are walking through the install, but then pointing out of the current toc depth to something at a different level while proceeding with steps 2 and 3 in the install.

That just seems wonky, right? I see why auth has its own section, but it doesn't seem like the docs are aware of their structure when making this suggestion and I could see a user being confused by this.

Oglopf commented 1 year ago

I think the simple fix is to flip steps 2 and 3, then move that "build from source" either out entirely (I'd prefer this at the start I guess, if we have to keep it) and then have that flows right into auth? Does that make sense?

johrstrom commented 1 year ago

I see that, the TOC is the issue. Let me see if I can't fix that up in this PR. I'll change #842 so that it doesn't do anything to these pages.

johrstrom commented 1 year ago

@Oglopf PTAL - I think it's actually quite simple fix now that you mention the ToC.

I see why auth has its own section, but it doesn't seem like the docs are aware of their structure when making this suggestion and I could see a user being confused by this.

Thinking about this - I don't know if auth should have it's own section. It's my guess that it should in fact be shown within the context of installing. Especially if the installation won't move forward without it.

johrstrom commented 11 months ago

I'm going to go ahead and move forward with this, it doesn't seem like it could be worse!