after a lot of evenings I was able to finalize my work on the navigation bar for our documentation site. It is all dynamic, meaning that contents of the menu is loaded via /js/nav.js data structure. This means that guides generated with asciidoctor can also have the same navigation bar, so the user experience is the same across the whole site.
I had to regenerate also stable branches 3.1, 3.0 and 2.5. I deleted 2.4 and 2.3 guides it was too much work backporting the changes for no benefit - the 404 page will explain what to do.
Things can improve now, if you spot a missing guide in the menu, or want to change something, it is easy to do. I also migrated the static site to nanoc which is trivial ERB-based Ruby site generator - much easier for our 5 pages than the previous one.
Next step for me is to convert our current Foreman documentation to asciidoc and start improving and modularizing the content.
We are also considering changing the menu to three columns:
Foreman on EL
Foreman on Debian
Katello
That looks more logical and clean, see screenshots here and let me what you think:
Also I want to convert our old manual to the new format and site so we can gradually extract and modularize bit by bit incorporating our new guides. What would you recommend this āoriginalā or ālegacyā manual be entitled? I was thinking like āOriginal Guideā or something like that.
Thanks for this massive improvement on the documentation site. I noticed the drop downs are quite small and many guide names need multiple lines. Can we widen the drop down? This worked for me on Firefox:
I think the name depends on the status/relationship between new docs and old manual. If I understand this correctly, weāre trying to move most content to docs.theforeman.org. Once this is stable and we declare it the āofficial documentationā, the old manual should be deprecated and only contain content that we havenāt/couldnāt/didnāt want to migrate (yet).
Once we remove the āWIPā warning, original guide sounds too positive.
Thanks for the patch, I briefly looked into this when I was fighting with JS/CSS but this is like Another World for me, I quickly gave up. It looks much better.
If anyone from our UI team is reading this, please try the new site on tablet/phone and fix possible bugs, I did not care doing that not that I donāt have a phone but I was too scared I would found issues without any idea how to fix them.
All the relevant CSS is in web subdirectory, we use sass to generate it.
I filed my migration PR with āComplete Guideā which is honest and friendly for readers - it looks like something I would totally click on when visiting for the first time. It is gonna be a long document, at least for the first year until we move content around therefore the word fits nicely. Once we move more content, we can drop some information about what is happening and why most of the content can be found somewhere else.
Iāll admit that I had no clue. I just used Firefoxās inspector, tried to add width and it auto-suggested the max-content value. Not having heard of it, I checked and it was exactly what I was looking for. I learned something new today
