theforeman
Build a dynamic customizable documentation wizard
This is based on a discussion with @apinnick and meant to showcase what could be done.
The past we've created many long documents with many options that the reader then has to choose. This creates a form where the user can choose ahead of time which options they want. These options get translated into attributes that writers can then use in the existing modules.
For simplicity it creates some very small guides now.
When experimenting I realized we really need a 2 step wizard:
- Select the guide
- Select the options for the guide
This is because the options will differ per guide. The disconnected installation doesn't have HTTP proxy or IPv6 content so presenting the option in the form is misleading.
Another thought is to include the OS selector so you only get the correct content. This also allows you to drop/reduce the supported operating system section.
The PR preview for 02eaeddebe7f7301f27fdc01c686394661672fce is available at theforeman-foreman-documentation-preview-pr-3741.surge.sh
The following output files are affected by this PR:
- Installing_Server/index-katello.html
- Installing_Server/index-orcharhino.html
- Installing_Server/index-satellite.html
![github-actions[bot] avatar](https://avatars.githubusercontent.com/in/15368?v=4 "Published by a pub.dev verified publisher"){kind=small}
I finally had a chance to check this out and it looks really cool. It would be nice to have this upstream although I realize it would take a lot of effort.
If writers think the approach is good then I can try to spend a bit more time on it. Hosting it shouldn't be too hard but then I'd first like an agreement
It does sound like a good topic for next week's documentation team meeting if you're still planning to join: https://community.theforeman.org/t/documentation-team-meeting-2025-04-10/42622
This is awesome! Thank you so much Ewoud!
Does that mean that we would move from a static site generator to Puma?
This is because the options will differ per guide. The disconnected installation doesn't have HTTP proxy or IPv6 content so presenting the option in the form is misleading.
We had a similar issue with the Sat Install Helper app. The connected/disconnected option was placed earlier in the checklist so that "disconnected" option hides proxy and IPv6. Are you proposing this wizard for upstream only?
One reservation I have is that we still don't know the effects of the d/s tooling changes. AFAIK, the migration process requires converting the files to DITA.
I don't plan to work on this myself anymore. If anyone is then by all means, please take this over.