Introduce a Foreman & DNS guide about foreman-documentation

[ekohl]

The outline I have written out can be considered a base for an assembly.

The steps I had in mind were:

• Enhance existing assembly to be complete
  • Complete #2933
  • Move external DNS into it https://docs.theforeman.org/nightly/Installing_Proxy/index-katello.html#configuring-external-dns_smart-proxy
  • Move https://docs.theforeman.org/nightly/Installing_Proxy/index-katello.html#configuring-external-idm-dns_smart-proxy
  • Remove DNS parts from https://docs.theforeman.org/nightly/Installing_Proxy/index-katello.html#configuring-dns-dhcp-and-tftp-on-productname_smart-proxy
• Remove DNS parts from https://docs.theforeman.org/nightly/Provisioning_Hosts/index-katello.html#Using_Infoblox_as_DHCP_and_DNS_Providers_provisioning and instead refer to the other guides
• Move assembly from Installing Proxy and create a new guide
• Make sure the guide also works on a ProjectServer

I think you'd mostly have a problem with the last 2 steps. We can also change that into including the assembly in Installing Server too.

Something to consider: we include firewalls? I don't like the current HUGE https://docs.theforeman.org/nightly/Installing_Server/index-katello.html#Port_and_firewall_requirements_foreman and would propose we drop port 53 there and instead add a firewall section to the DNS assembly.

Once we've done this for DNS, I'd like to do the exact same thing for DHCP. TFTP is another candidate.

[ekohl]

This sounds like a networking guide.

Networking guide could be an overloaded term, because networking can mean a lot of things. Networking can also mean how you set up networking for individual hosts. Or overall how you set up Foreman and individual Smart Proxies to be networked.

I might be wrong but I see DNS and DHCP as part of planning/installation.

DNS and DHCP can be needed for provisioning, but if you (initially) don't use provisioning there's no reason to follow those steps. Or, if you use image based provisoning then DHCP may not be needed at all. You could still use DNS then.

It may also be installed after the fact, when you do start using the features. I see it as an optional feature. That means you probably want to touch on it as part of planning (do you immediately install it or leave it until later?).

[apinnick]

Ewoud and I discussed possible titles. We both liked "Managing DNS and DHCP". Does that sound OK?

[asteflova]

Proposals for guides based on features (like DNS) always make me suspicious. I prefer guides based on stages of a product's lifecycle or a user's journey (planning, installation, deployment, maintenance, ...). But maybe we could make both work..?

What if we avoid thinking about guides at this point and instead focus on reviewing and polishing assemblies related to DNS? Then, once we have those assemblies, we could decide whether an assembly belongs to, for example, an Installation guide or a dedicated DNS guide... or both (through assembly reuse).

One thing that we used to consider for modular docs was adding tags to enable filtering and even building 'custom' guides. That's the way I'm thinking about this: adding hypothetical tags to assemblies (DNS, Installation, Deployment, Server, Proxy, ...) and then composing guides based on these tags (Server Installation guide = guide that includes all assemblies tagged with Server and Installation; DNS guide = guide that simply includes all assemblies tagged with DNS; ...).

To clarify: I'm not proposing we actually start using tags in assemblies. Thinking in terms of tags simply illustrates this approach to organizing content into guides.

So, am I making things unnecessarily complicated here? :)

[apinnick]

@ekohl This sounds like a networking guide. Is that what you are proposing?

RHEL and OpenShift have separate guides because network configuration is a huge and complex subject.

[apinnick]

Proposals for guides based on features (like DNS) always make me suspicious. I prefer guides based on stages of a product's lifecycle or a user's journey (planning, installation, deployment, maintenance, ...). But maybe we could make both work..?

@asteflova I might be wrong but I see DNS and DHCP as part of planning/installation.

[apinnick]

This sounds like a networking guide.

Networking guide could be an overloaded term, because networking can mean a lot of things. Networking can also mean how you set up networking for individual hosts. Or overall how you set up Foreman and individual Smart Proxies to be networked.

I agree with this in principle. However, I feel some hesitation in using extremely specific terms in titles because, at some point, someone will probably want to add a section that does not quite fit the guide's title. Is there a title that is more specific than "networking" but with enough room to allow similar content?

Maybe my concerns are groundless. If you think that we have enough material for this guide and that its contents are not likely to change/expand, then the title is fine.

I might be wrong but I see DNS and DHCP as part of planning/installation.

DNS and DHCP can be needed for provisioning, but if you (initially) don't use provisioning there's no reason to follow those steps. Or, if you use image based provisoning then DHCP may not be needed at all. You could still use DNS then.

It may also be installed after the fact, when you do start using the features. I see it as an optional feature. That means you probably want to touch on it as part of planning (do you immediately install it or leave it until later?).

True. But even if they are optional, I think they would still be part of planning/installation. I need to think about this.

[ekohl]

Maybe my concerns are groundless. If you think that we have enough material for this guide and that its contents are not likely to change/expand, then the title is fine.

We can debate titles and naming is hard. I'd argue DNS integration guide could be a good candidate.

True. But even if they are optional, I think they would still be part of planning/installation. I need to think about this.

Yes, IMHO this is something we should do in general. I'd think that the planning guide lays out the general path so that you, as the reader, can make a plan on how to deploy. So all the optional parts should be touched on. I can imagine we'd also describe other parts, like managing Puppet, Ansible, etc.