Problem: Out-of-date instructions in the main Foreman manual for v2.1.0 and likely earlier in “3.2.3 Installation Scenarios” (Foreman :: Manual)
There are two instances of the following:
Fill in the OAuth consumer key and secret values from your Foreman instance, retrieve them from Administer > Settings > Authentication , and set the Foreman URL appropriately.
At least in Foreman 2.1.0 (and possibly earlier - not verified), the values for the mentioned OAuth Consumer settings are (I believe - correctly) redacted, as can be seen in this screen shot (logged in as “admin”):
The reader should instructed to run the following (or similar) command on the foreman server system, to extract the key and secret required for the procedure being documented:
I’ll leave it to the documentation/developer teams to decide how they would like to document this procedure and whether to prefix the command with sudo(8), or assume the user is running as root.
With encouragement from @mcorr in a previous topic, I’ll be bold and suggest the following:
Starting Assumption: By limitation or convention, subsection numbering only goes to three levels.
Section 3.2.3 “Installation Scenarios”, should be promoted to one level higher (say 3.3), so that each scenario can be given its own subsection numbering, and thus appear in the LHS Table of Contents when rendered online. So specifically, “Using an external database server”, “Setting up Foreman with additional Smart Proxies”, “Standalone Puppetserver”, … are promoted to be in the LHS ToC. And yes, I realize the “Installation Scenarios” are “Foreman Installer” installation scenarios, so the subsection heading may need to be changed.
The section “Setting up Foreman with additional Smart Proxies”, (sort of) just stops after outlining the required process in English. Especially the “2. Run the standalone installation as detailed below”, as there is nothing below, as a new subsection starts on installing a “Standalone Puppetserver”.
I, in fact, blindly copied the command line example from the next subsection into my notes and updated with my details, and run that and it worked (for what I was testing - creating and registering another smart-proxy). Where as the actual commands to run (for provisioning tasks - my intention) are in the subsection “Smart proxy for DNS, DHCP etc.”. In fact, that last mentioned subsection mentions the certificate requirements from the first mentioned subsection.
Maybe these two subsections should be closer together or merged. I personally would like to see a small reminder sentence in each scenario, to remind the user why they might wish to undertake this scenario - for me - I wanted to test that I could deploy a smart-proxy at a simulated offsite location to install systems (actually VMs on VMware vSphere/ESXi). Without referring back to other documentation, I can’t as yet (as a new foreman user) answer the question: should I be configuring my remote smart-proxy with puppet? I know I need TFTP, DHCP, … to provision systems at that site, but do I need a proxy for puppet to provision my VMs? (Aside: I’m not using puppet to manage systems, so probably not, but I will be using Ansible, so should I configure the Ansible feature on the remote smart-proxy? For myself, refresher reading will be required as I design/build my first non-test Foreman VMs - I know I have read the answer to the questions I just posed, I just don’t remember design guidelines for these cases - but the overall concepts are slowly sinking in )
In the section “Setting up Foreman with additional Smart Proxies”. For users not versed in the puppet universe, the sentences proceeding each of the following commands " puppet ssl bootstrap …" and “puppetserver ca sign …”, could be augmented with the host to run the command on; the first is the new smart-proxy only system, and second is the foreman-server system (if it is an all-in-one installation or your PuppetServer/CA system). While I knew which hosts to run which commands on, it is really not obvious from the documentation that this is required. Also a reminder that the firewall on the Foreman All-In-One (or PuppetServer/CA) will need to allow remote connections to the puppetserver process (on port 8140 by default) would be nice, as the error you get is cryptic (IIRC, “No route to host”, and not the expected “Connection refused”)
In “Setting up Foreman with additional Smart Proxies”, starts with scenario description (which is good), but sentences: “On the Foreman host, run a complete foreman-installer all-in-one installation to provide Foreman, a Puppetserver and Smart Proxy. This will be the Puppet CA.” - I feel needs a little work, especially the “This will be the Puppet CA.” part. Maybe just adding “host”, after “This” would work, but maybe it would be better to split sentences differently, and state that the default all-in-one foreman-installer server will host the foreman application and additionally act as a local smart-proxy, database server, puppetserver and puppet CA (Certificate Authority).
I hope this feedback has been a useful insight into one new user’s journey in to that small section of the documentation.
This is slower, but guaranteed to be correct. You can also skip passing keys and grep IIRC.
PRs to https://github.com/theforeman/theforeman.org/tree/gh-pages/_includes/manuals/2.1 are highly welcome. Note that we also have a nightly directory and in the end they need to be in sync. Otherwise we’ll have it wrong again in 2.2 but this is not required for the initial PR. It can be easier to first sort out the text and then update nightly.
Thanks, but the point was to raise issues with the main Foreman manual to improve its usefulness.
Also for CentOS users, RedHat instructions don’t always have command equivalents in CentOS even though they are the same core Operating System, example subscription management. But I agree the initially RedHat documentation is worth knowing about and reading for CentOS users.
Quick Question: When should we be using Foreman’s issues tracker for report bugs/… vs each project’s specific GitHub issue tracker? I have only seen references to Foreman’s issue tracker in the 2.1.0rc* process topics on the community.
True, the documentation source code supports that - nice to see the use of such systems for the project’s documentation.
But I was also thinking of how CentOS / Foreman and RHEL / Satellite (and even RHEL / Foreman) differ in terms of installation procedure, with Foreman having one way to approach each procedure, and Satellite using its own commands / infrastructure for the same procedure. For example, regardless of Enterprise Linux distro (CentOS or RHEL), a hypothetical procedure for say “Installing the Installation Commands”, might discuss say ‘adding Foreman repositories’ for Open-Source Foreman users, while the Satellite product documentation might discuss it terms of ‘using subscription-manager to subscribe to the Satellite product suite’. The final rendered documentation for each product, should only mention the procedure relevant to each product, so the reader does not have to digest information which is not relevant to the tasks they are undertaking.
On the possibly incorrect assumption that the documentation teams work for two masters: The Foreman project and the RedHat Satellite product suite. The Foreman project also has bit more of burden, in that they need to, ideally develop documentation the Satellite team can use, by appropriately using the aforementioned variables. They also need to support platforms that the Satellite product suite may not currently support like: Enterprise Linux derivatives (CentOS) and Debian & its derivatives (Ubuntu) - making parts of the documentation conditional on both Product and OS combinations. Which, I hope, the Open Source Foreman project users (like myself), appreciate is no small task to back port that documentation to the Foreman project without harming the quality of the documentation they need to produce for a commercial product. The joy just multiples when you consider the additional variable of each product having its own version numbers
Do take care when promoting chapters, we have chapter names and numbers hardcoded in the filenames and also any kind of renumbering will ultimately break all the links we have on forums or in the app.
We have recently discussed with @Shimon_Shtein possibility to create an Appendinx-like document as the langing page for all links from the app and as the preferred place to link content from the forums and emails. It could then lead readers to both upstream RH documentation and our official docs.
This is all quite possible from the one source we have. It’s a judgement call. For example, if the procedure is largely the same but just requires slightly different commands, we can reuse up to 100% of a file. If the procedure is 70% similar, we can reuse and add in if statements to cater for both scenarios. This continues until it would make sense to create some upstream-only content that builds only for Foreman. We can modify the docs on a sentence level or a file level. There’s a lot of flexibility. We’re at the stage now where we have to look at how we put it all together.
Yes, I noticed that, that’s why I started that section with “I’ll be bold and suggest the following”, but than forgot to mention it maybe non-trivial. Also I only looked at the source to one or two sections of documentation and I don’t personally have experience with the documentation system in use, but it strikes me as the same problem that SGML and hence XML, and hence HTML have, you have to have a good naming system for id tag values (i.e. anchor point names), while keeping the names manageable over the long term. From my CS degree (all those many years ago), I partially remember a quote of the form: “There are two hard problems in Computer Science: Problem Decomposition and Naming Things”.
PS: Googling that returned the funnier (if your a programmer) quote of: “There are 2 hard problems in computer science: cache invalidation, naming things, and off-by-1 errors.”
)