Planning for deprecated documentation (was "Remove deprecated")

[apinnick]

We should plan for deprecated functionality in our documentation.

• Add deprecation notice (seems to be the current practice).
• Review the affected documentation for any content that is not deprecated.
• Create an issue?
• Ask engineering about removal plans?

---

Old description
Some features take a long time to be removed, so they stay in a "Deprecated" state for a long time.
Meanwhile, procedures like "Registering hosts with a bootstap script" take up space.

I have a suggestion for dealing with this:

• Remove procedures relating to a deprecated procedure, starting from the version in which the deprecation is announced.
• Retain the section header with a deprecation notice and a link to the procedure in the guide that last supported the feature. Alternatively, remove the section header and add the deprecation notice and link to the beginning of the assembly.

The user still has access to the deprecated procedure but the procedure does not take up space.

[ekohl]

I think this is questionable. For example, things may change in the procedure (because they happen in a non-deprecated part). That makes it harder to follow.

While this may be wishful thinking, I think it's preferable if we improve our deprecation process and actually follow through with removal.

[apinnick]

I think this is questionable. For example, things may change in the procedure (because they happen in a non-deprecated part). That makes it harder to follow.

Can you show us a real example? Why would anyone update or change a procedure when the feature is deprecated? See Registering hosts with bootstrap script.

Agree that it would be best to remove deprecated features in a timely manner. This is an attempt to reduce doc bloat.

[ekohl]

Can you show us a real example? Why would anyone update or change a procedure when the feature is deprecated? See Registering hosts with bootstrap script.

It has steps to sign a Puppet certificate. That isn't part of bootstrap and common to other aspects of the application so it's not going away. There we could change make changes in how you sign certificates. The result is that the older procedure won't work on newer versions anymore.

Currently entirely theoretical, but you're proposing a change in how we approach it.

[apinnick]

It has steps to sign a Puppet certificate. That isn't part of bootstrap and common to other aspects of the application so it's not going away. There we could change make changes in how you sign certificates. The result is that the older procedure won't work on newer versions anymore.

In that case, we need to start planning as soon as a deprecation is announced. Otherwise, when the feature is finally removed, it will not be straightforward to update the docs. Any procedure that is not being deprecated needs to be moved to a new location asap.

[ekohl]

Would it make sense to add notes to procedures that are deprecated?

[apinnick]

Would it make sense to add notes to procedures that are deprecated?

The procedure already has a deprecation notice. I am proposing that the procedure be removed completely and replaced with (a) deprecation notice and (b) link to procedure in an earlier guide.

Otherwise our docs turn into graveyards where deprecated features go to die but don't quite succeed. :-)

If a procedure needs surgery to remove something that has not been deprecated, that needs to be done asap.

[asteflova]

What exactly does it mean for a feature to be deprecated? As far as I know, for RH d/s, a deprecated feature means a feature that is currently still supported, but won't be in the future. If this is the case, then we shouldn't remove deprecated docs. (For example, it's still possible that a deprecated feature receives critical updates, which might mean that docs from a previous release might not be entirely up-to-date.)

[Lennonka]

I agree with Anet ^^

Btw, removal of documentation should be planned together with development working on removal of the deprecated feature during the release cycle.

[asteflova]

Otherwise our docs turn into graveyards where deprecated features go to die but don't quite succeed. :-)

I agree that this is not optimal. Rather than drop things on the docs side only, this might be a good opportunity to start a cross-team conversation about dropping the features themselves.

[ekohl]

The procedure already has a deprecation notice. I am proposing that the procedure be removed completely and replaced with (a) deprecation notice and (b) link to procedure in an earlier guide.

Sorry, I missed that.

I think @asteflova phrased my intention better. A deprecated feature is still supported. The general rule Satellite has always used is that anything that's documented is supported, other things are generally unsupported. So by removing the docs, you're effectively changing the support status.

Removing it from docs is a bit like pretending the problem doesn't exist. Having a proper plan in place to remove features would also have my preference.

[apinnick]

Sounds good to me. I'm going to update the issue name.

[maximiliankolb]

I think this is very valuable, esp. for enterprise customers. We can differentiate between "something that we mark for deprecation for an upcoming release" and "something that we know is gone with X.Y for which we can add an admonition to X.Y-2".

Marked for deprecation

This is something that I'd only show for upstream with a wording similar to "This feature might get removed in an upcoming release." if at all. Example: bootstrap.py

If Devs start actually* removing a certain feature, we should adjust the docs. I'd only include a note for Satellite and orcharhino if it has been removed from Foreman nightly and therefore for sure will be gone with an upcoming release. I imagine that this is something for which we have to rely on pings and/or general community interaction, such as Foreman Community Demos. Maybe we can reach out and let everyone know that we are interested in deprecations?

*example: katello-agent was deprecated for some time ...

Removed features

If we know that Foreman X.Y does not longer support a specific feature, we should always mention this in X.Y-2. When we drop docs from "master", we should at least open an issue to add a deprecation warning for X.Y and X.Y-2.

A small standardized comment // marked for deprecation; gone with Foreman X.Y would be great so that we can grep for "marked for deprecation" :)

[ekohl]

I'd only include a note for Satellite and orcharhino if it has been removed from Foreman nightly

I disagree with this. Some features are big and sometimes users need more time to be warned. Upstream example: we announce running on EL8 is deprecated a few releases before it actually happens.

therefore for sure will be gone with an upcoming release

This is the important part: you need an explicit timeline.

If we know that Foreman X.Y does not longer support a specific feature, we should always mention this in X.Y-2. When we drop docs from "master", we should at least open an issue to add a deprecation warning for X.Y and X.Y-2.

I disagree with this in the general case. While there are cases where it makes sense to create additional visibility, I'd say that if you want to give users 2 releases to migrate, then you deprecated it with X.Y, repeat the deprecation with X.Y+1 and remove with X.Y+2. If a feature is small enough that 1 release is sufficient, then it's easier.

The important part is that we have this discussion for every deprecation and agree on a plan. Right now that's not really happening.

A small standardized comment // marked for deprecation; gone with Foreman X.Y would be great so that we can grep for "marked for deprecation" :)

This can be very disruptive. Look at katello-agent removal. It affected a lot of files and was all over the place. Do we want to track all of that?

If there are specific procedures, I'd argue that we want to make it even more visible: add reader-visible deprecation notes.

But all in all, I'd say this is broader than just documentation. https://community.theforeman.org/c/development/rfcs/18 is IMHO the proper place to discuss this.