Build a dynamic customizable documentation wizard #3741
Conversation
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.
github-actions
bot
added
Needs tech review
|
The PR preview for 02eaedd is available at theforeman-foreman-documentation-preview-pr-3741.surge.sh The following output files are affected by this PR: |
|
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 |
|
That was my thought exactly |
|
This is awesome! Thank you so much Ewoud! Does that mean that we would move from a static site generator to Puma? |
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. |
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:
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.