New docs - urls

Support
1

I have noticed recently that a couple of people installed the nightly version, I guess by accident. I wondered why and noticed myself that a few times I have been on the nightly docs when I was browsing.

One way I get there if I am in a manual like the installation manual for katello 2.5 https://docs.theforeman.org/2.5/Installing_Server_on_Red_Hat/index-katello.html and what to go to the upgrade manual. Thus, lazy as I am, I just cut the URL to https://docs.theforeman.org/2.5/ thinking, that must be the 2.5 page. It also gives me the selection of guides. If you are just in transition you don’t really look at the three head lines:

Page not found!

We are sorry, but this page does not exist.

Available guides for the latest nightly build:

So if I continue there I am in nightly docs. The correct URL for the list of 2.5 guides is https://docs.theforeman.org/2.5.html

May I suggest to move the version page 2.5.html to 2.5/index.html aka 2.5/ ?

As all guides are under the 2.5/ location the guides index is, well, the index for that location. Add a redirect from 2.5.html there to keep old bookmarks working.

Also the general 404 error page should not be the nightly guides index. Any URL which doesn’t exist, e.g. https://docs.theforeman.org/lksdjhflskjfh takes me to the list of nightly guides. From that it’s not really clear that you are on a 404 error page. IMHO that error page should contain the top page https://docs.theforeman.org/ if you want to keep it that way.

May I also suggest to make the nightly docs more obviously “nightly”? I guess that would help people to identify those pages as “beta version” and keep them from accidentally following them. I thought about something around a big watermark with “nightly” or “for development” or “beta” and maybe also a static, floating element at the top of each page explaining this is nightly docs and briefly mentioned the indented audience.

5 Likes
2

cc @lzap @mcorr and @lstejska just in case you haven’t seen this.

3

I had not seen this! Thanks @Marek_Hulan and @gvde - looking now.

4

IIRC, this is needed because we are using hugo. I’ll try to catch up with @lzap and see can we implement redirects.

5

This is not technically possible, however I am making a change that will copy X.Y.html files as index.html pages. It makes sense, this happened to me as well.

Agreed, this is also confusing. Both changes are here:

This is gonna be more tricky change - we need to change ASCIIDOC template (CSS). I will take a look.

3 Likes
6

I have found a way how to implement “Fork Me on Github” ala ribbon:

2 Likes
7

Now the demo is over, I will review these PRs!

8

Which then creates content for a new demo :slight_smile: I think we should present these changes and the whole docs again.

9

I still have to finish off a few bits before it can become “official”, but I’ll definitely go through it at the next demo!

2 Likes