In the end, we would like the content to be split among the current books, but for the first phase I think it would be good idea to create a brand new book with the all content unchanged so we can switch over to the new format, find issues and update our homepage to link it. Overall the goal could be to make the transition phase when we would be updating both places minimal. After that, we can start breaking content up adding modules and references so the same content is reused in the newly created book and other ones. This should bring no disruption to readers who are used to our old documentation while providing new content to the new documentation set we can sometimes switch over to.
Now, I have this task in my agenda for a long time but I am not getting to it. Is there anyone willing to do the conversion? There must be tools, maybe this can be semi-automated. Let me know and I will fill you in.
If you see this as a completely differnent project, then we don’t need to sync. But I was hoping there might be some synergies.
Any feedback is appreciated.
As for converting markdown to asciidoc: We’ve converted docs from .rst to asciidoc which involved a lot of manual labor after running pandoc. I would certainly participate in this endeavour. Please let me know if there are specific tasks that need to be worked on.
For the Foreman QSG and Installation guides, we will have to take a different approach, but for the rest of the documentation, we will not progress in our effort to create improvements if we silo everything off into plugins, in my opinion.
My understanding was that we would add feature parity at docs.theforeman.org with each of the plugin manuals, but we would not duplicate the current plugin manuals at docs.theforeman.org.
Okay, so if I understand correctly you are more against my skeleton and the issues with silos than adding plugin documentation as a whole?
You would rather not call it “plugin docs” but just “docs”, i.e. have it incorporated to the usage guides?
I think you’re absolutely right long term, but short term, it’d be easier to move (not copy!) documentation for plugins (github, readthedocs, etc.) to the upstream Foreman documentation. Work on the structure can IMHO happen at a later stage.
IMHO the later stage never happens.
If we migrate plugin guides from one place to another, what do we gain?
The majority of the content of the plugin guides exists in the user guides but is just not as up to date or tailored to the community as it needs to be.
With the Ansible plugin manual, for example, I measured what was in docs.theforeman.org against the plugin guide, updated the docs.theforeman.org version, and I hope to now start to sunset that plugin manual. My plan is to do this manual by manual.
I am fine with the installation manuals and QSGs moving to docs.theforeman.org, but see zero value in a migration of existing plugin manuals to docs.theforeman.org.
I closed the PR on github. Sorry for hijacking this thread. I’m obviously still up to participate. Maybe I just need some more concise instructions …
This is more than likely my fault. I am happy to discuss any ideas that you might have. This work requires a lot of effort to get right. As I’ve moved from docs to this role, I haven’t always had the time to do dedicate myself to it as much as I want.
One fun part about plugins is that they have their own release cycles. That means you can even have a major version bump in a stable release. That’s why they have their own structure.
Concrete: you can have a Foreman x.y with MyPlugin 1.0. During the release cycle of Foreman x.y, MyPlugin can be updated to 2.0.
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).
If you take a monolithic view of a Foreman release that Foreman x.y always has a certain MyPlugin version, you limit yourself to what’s in our packaging repositories. It also means that cherry picking a plugin version (especially major version) also means docs cherry picks.
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.
In a way that the content in the original book stays almost unchanged, we would extract those interesting parts which are missing in our new documentation into asciidoc modules (separate included files) and once we are happy with it, we would do the switch.
IMHO as long as we deliver the plugin documentation modularized (just a fancy word for content written in includable separate asciidoc files), we can have both versions - one that is integrated in a more friendly way and one that is for someone who just wants to read about a specific plugin.
It’s a little bit more than this. It is an approach that focuses on workflows rather than feature descriptions. The module types are organized into specific units of information so that they can be combined into chapters and guides that provide end to end workflows. A lot of the plugin manuals are written in a fashion where they cannot just be chopped but should be rewritten entirely.
It would be ideal if we could start improving upon this in docs.theforeman.org. My immediate idea would be to maintain a compatibility table. Perhaps make updating that table part of the plugin release process. If you have other suggestions, I would love to hear them.
For Katello also, we’ll need to maintain branches. I worry that those of us who understand the relationships well will intuit this, but we might need to create a chart for those who are working largely for Satellite and or just unfamiliar and want to contribute.
Interesting, you should have seen the size of the guide I cut this out of
Not to make little of what you’re saying, but some of this comes down to taste.
For example, some people argue that we should have one large user guide with scores of chapters, and allow the user to ctrl + f for what he or she is looking for. They think that breaking it into small pieces makes it necessary to jump in and out of guides constantly
As for plugins, today there is nothing else than to look in the repo or directly what the gem claims to support. In theforeman-plumbing/packages at master · ekohl/theforeman-plumbing · GitHub I once tried to write a tool to generate a dashboard. Technically I could extract all information and the services should still work but I hated writing the UI for it so I gave up. They can probably be converted into scripts as well.
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.
Now I’m not sure I want to
I think Integrating with AWX is something that is a completely different workflow than managing roles. The only shared thing is Ansible, but it has nothing to do with the Ansible plugin. You don’t need the Ansible plugin installed for that to work. However, the current document does give you that impression. In other words describing the current documentation: you won’t see Integrating with AWX in the foreman_ansible plugin documentation but you could see it in the core documentation.
Also, I’m lost on 4.2 because I think steps 8 and 9 aren’t needed. See the template. It enables the service so on the next boot (right after kickstart) it should automatically run it already. Perhaps that should be a different discussion though.
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.
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
