Volunteer needed: Documentation conversion

[tbrisker]

@ekohl

Generally speaking a Katello release maps to exactly one Foreman release. With one exception (Katello 3.10) one Foreman release also maps to exactly one Katello release. I think it’s safe to assume Foreman is leading and that gives you exactly the Katello version. forklift/versions.yaml at master · theforeman/forklift · GitHub is probably the best reference here. Also lists the Pulp versions. Note that Puppet is one version and that’s the one we test with but it’s not the only version we support. Generally there is a wider range.

Perhaps the best approach we can take is to version only by Foreman versions and have all plugin-related content (whether separate or combined) match the latest version of the plugin in that branch? While sometimes we do have major releases in plugins mid-stream, it’s fairly rare there are actual changes that need documentation updates. In fact in most cases the manuals for plugins are rarely updated and when a new version is added to them it’s usually copy-paste from the previous one.

[ekohl]

@mcorr

I tested this full workflow back in the day with the help of Stephen Wadeley and also Sachin. It could very well have been updated sometime in the last three years. PRs welcome

The steps work, but 8 and 9 should never have been needed because they’re redundant. It could be that there was a bug that required it, but that bug should be fixed upstream rather than worked around in documentation. One thing I can imagine is that it misses a After=network-online.target or similar so it tries to run before the network is available.

[ekohl]

@mcorr

I think that we need to get workflow oriented rather than plugin oriented. I suppose that was the whole point of rejecting Maximilian’s proposal to migrate and convert the plugin docs. For me the idea is that we cover workflows. Ideally a long workflow is a guide and shorter ones are chapters.

Right, and I generally agree. In this case I would argue that Integrating with AWX is its own workflow.

[mcorr]

@ekohl

Right, and I generally agree. In this case I would argue that Integrating with AWX is its own workflow.

It has been given a standalone chapter in its own guide. We debated it at the time in the PR. It’s very short to be out on its own. I don’t feel particularly strongly about this though. If someone wants to break it out into a standalone guide, fine by me.

[lzap]

@mcorr

It’s a little bit more than this.

Yes, that I know but I was hoping that the technical possibility of including sections would get us onboard. During extraction to modules, we would need to meet the standards of the RH documentation.

@tbrisker

Perhaps the best approach we can take is to version only by Foreman versions and have all plugin-related content (whether separate or combined) match the latest version of the plugin in that branch?

I like this.

@tbrisker

While sometimes we do have major releases in plugins mid-stream, it’s fairly rare there are actual changes that need documentation updates. In fact in most cases the manuals for plugins are rarely updated and when a new version is added to them it’s usually copy-paste from the previous one.

If this happens, we can easily simply backport plugin-related documentation updates into a Foreman stable documentation branch.

@ekohl

The steps work, but 8 and 9 should never have been…

While I really appreciate your involvement in documentation in general, I think this thread is slightly going towards “how to improve Ansible Guide”. To get this back on track:

@ekohl

The current documentation takes the approach of leaving it up to the user to figure out which version they have installed and read the appropriate documentation. This also means users can install from source (and we can consider containers source builds).

And I believe this is bad. If you follow our installation procedures, there is no discussion about what plugins are compatible - it just works. If not, we fix this because we try to be consistent. And we usually deliver pretty solid set of plugins in regard to stability - most of them work fine.

We also moved away installation from source from our installation guide into the development section for good. We don’t want to encourage people to do this, it’s tough thing to install Foreman with some plugins. Compatibility matrix is a good example - you need that. And lots of know how on how to configure things with backend services, certificates. If you opt-in into installation from gems/source you should be prepared for problems.

I am pretty bad in maintaining compatibility matrixes for my plugins, today’s morning I received an email from a stranger who asked what discovery plugin version is compatible with 2.3. I forgot to update the table once again! And I have to tell you, the only reason discovery document exist is the table, everything else is well covered in the new documentation and I should probably take the content down as it’s getting less and less relevant.

We can write a tool that extracts all compatible versions from our yum repository metadata for each Foreman release creating one big table so we don’t need to maintain this anymore. We can publish it anywhere - wiki, webpage, new document or appendix.

@ekohl

What I don’t like about this document is that it is one huge document with a lot of unrelated procedures. I would really like those to be split out to separate documents, all related to the Ansible plugin. A separate plugin manual does facilitate that more than monolithic documentation.

Frankly, I don’t see any reason to do that any other that the compatibility matrix I struggle to maintain for my plugins given the fact we no longer want to push the gem/source installations. I mean, containers are ahead of us, some day we will ship certified containers so it’s not like we are going the wrong direction.

However, if we still find reasons to maintain separate documents, there is a technical possibility (including files) to assembly those. I just don’t see the need at the moment,

I would love to see us to come to some conclusion how to approach the migration to the new format at least. Here are things which come to my mind which needs to be sorted out:

• Figure out how to do branching and directory structure for the new documentation: Change publishing dir to nightly by lzap · Pull Request #360 · theforeman/foreman-documentation · GitHub
• Explore what the conversion options from markdown to asciidoc are
• Do some initial draft conversion and present how it’s gonna look like
• Merge most remaining PRs in the old documentation
• Perform the conversion
• Make an update in the old docs with every chapter linking the new destination (so in case people just land there and click on 2.4 they get something)
• Update Foreman core documentation links to point to the new site