The upstream versions of the Foreman and Katello projects become, among other downstream projects, the Atix’s Orcarhino and the Red Hat Satellite of tomorrow. The discussions and contributions that take place in the vibrant upstream community shape the code base. The code base begins upstream and moves downstream. Until now, the Satellite documentation did not follow the same journey. In this blog, I will outline what has been happening with Satellite documentation over the last year and how this benefits both the Foreman community and Red Hat Satellite users.
One idea that we could implement and which I’ve discussed with @Shimon_Shtein is that we have links hardcoded in Foreman codebase to upstream and Red Hat. These links get broken quite often, I was suggesting we create a dedicated “appendix” style document which landing archors for all links we have in Foreman (about a dozen of them). It would contain short explanation of the term and then link both into new documentation and the official documentation. We could easily make sure that anchors in this document won’t get renamed, moved or deleted (using a warning comment). It also helps the users to find the right content in both documentation sets and also us to map what we actually have or missing in both so we can start working on this.
Hi Lukas, that is a good idea. From what I can tell, there is no functionality in AsciiDoc to redirect links, so your suggestion is the easiest way of solving it. The drawback is that users need to click one time more to get to the page required, but that is definitely better than bumping onto a non-existent page.
Moreover, there is such a page already - the Appendix A: Technical Users Provided and Required by Foreman in the Planning guide. The glossary already defines many terms, what we need to do is to add links to the actual docs that show how to use the functionality. And add the terms that are not defined yet if required.
I will investigate a little more if AsciiDoc redirects are possible. If not, we can link to this doc from the UI doc buttons.
This is a feature, not a bug. I would like to allow them to read one sentence overview and then having the ability to follow several links as preferred, including links outside of our documentation.
The Appendix B is probably good enough, what you think @Shimon_Shtein ?
This gives me the correct URL however in AsciiDoc I need to enter it like this: see {BaseURL}content_management_guide/managing_activation_keys#Managing_Activation_Keys-Creating_an_Activation_Key[Creating An Activation Key] in the _Content Management_ guide.
Finding all cross references is non-trivial, I am trying to find a tool to semi-automate that. We need this landing page to be perfect and really full of all links across the whole book set and beyond.
One thing I noticed is that directories of the final destinations do not match the directories in git. Example:
Provisioning Guide has directory named doc-Provisionin_Guide and on the RH portal the URL is /6.7/html/provisioning_guide. I know there is some software behind the scenes, I think it is the right time to solve this. We want these URLs to be the same upstream and downstream. Ideally this would become: https://docs.theforeman.org/2.1/html/provisioning_guide.
Can you give me a little bit of context what kind of software is this? Up until now, we’ve been using Makefiles to do the builds. We can either modify the makefiles to create the very same directory structure or start using those tools.
I am not sure that glossary is the right landing page: We have a couple of docs buttons that lead to process documentation. Besides that, I don’t think there is one-to-one relation between upstream and downstream topics. I think it’s good, since as @spetrosi mentioned, the docs are built from different points of view - feature vs use cases.
Personally, I think that resolving permalinks should be done on docs server side. It should be done either by asciidoc web serving framework, like here: https://github.com/asciidoctor/asciidoctor.org/blob/master/docs/asciidoc-quick-reference.redirect, or by a dedicated web server with single resolving purpose, like it was done on microsoft’s site.
