Updated ToC for entire ManageIQ + added already existing topics within ToC #1806

qahmed1998 · 2024-08-22T23:58:21Z

Added following additional topics to ToC:

Creating a Service in for Virtual Machine Provisioning
Service Provisioning Using an Orchestration Template
Assigning a Custom Analysis Profile to a Virtual Machine

This PR is editing the current ToC for ManageIQ. No files in terms of their locations were moved in the process. 3 existing topics (as mentioned above) were added to the ToC.

Added following additional topics to ToC: - Creating a Service in for Virtual Machine Provisioning - Service Provisioning Using an Orchestration Template - Assigning a Custom Analysis Profile to a Virtual Machine

Fryguy · 2024-08-26T14:40:49Z

@qasim-ahmed This PR is going to need a bunch of "prior" entries, so that the page detector can understand how the pages were moved around. Basically, the way it works is for each of these "moved" sections, just add a new key called "prior" which is the url for the old location of the file. Here's an example from when we moved one of the locations from morphy to najdorf: https://github.com/ManageIQ/manageiq-documentation/blob/najdorf/_data/site_menu.yml#L42

Fryguy · 2024-08-26T14:41:58Z

@qasim-ahmed Can you also update the original post here with maybe a screenshot or a manual type-out of the new layout? Also, please update the PR title / commit message to be more descriptive - this is a pretty big change, and the title doesn't really reflect that.

qahmed1998 · 2024-08-26T15:21:26Z

Installing section:

Upgrading section:

Administration section:

Visualizing section:

Controls section:

Managing integrations section:

APIs, Reference and Troubleshhooting sections:

Fryguy · 2024-08-28T14:39:19Z

@agrare @jrafanie Please also take a look.

qahmed1998 · 2024-09-05T14:35:21Z

Hi @agrare @jrafanie Please take a look when you get a chance.

jrafanie · 2024-09-05T18:59:08Z

@qahmed1998 how can I see a before and after?

It's hard to visualize what's moving around and being added/removed. I'll add my comments but they're on the existing terminology so mostly unrelated to this PR.

jrafanie · 2024-09-05T19:01:31Z

_data/site_menu.yml

    - title: Methods Available for Automation
      path: "/docs/reference/latest/methods_available_for_automation/index.html"
      desc: Advanced automation methods for ManageIQ Management Engine
+    - title: Scripting Actions in ManageIQ
+      path: "/docs/reference/latest/scripting_actions/index.html"
+      desc: "Real-time, bi-directional process integration for ManageIQ Management Engine"


What's the difference between ManageIQ Management Engine and ManageIQ? I see both terminology here. Do we need to normalize on one term?

FYI @Fryguy

Note, I see this term elsewhere so we can potentially normalize the terms in a followup PR. It's more obvious here since I see both forms of what I think are the same thing.

I bet this used to be CloudForms Management Engine. Probably best to just use "Real-time, bi-directional process integration for ManageIQ"

qahmed1998 · 2024-09-05T19:01:45Z

@qahmed1998 how can I see a before and after?

It's hard to visualize what's moving around and being added/removed. I'll add my comments but they're on the existing terminology so mostly unrelated to this PR.

We can potentially merge and see the ToC?

agrare · 2024-09-05T19:09:19Z

We can potentially merge and see the ToC?

I think that defeats the purpose of PR review if we have to merge it to see it, agree with @jrafanie it is hard to review without seeing what has changed easier

qahmed1998 · 2024-09-05T19:10:39Z

I have posted screenshots above as well. The ss might help!

_data/site_menu.yml

agrare · 2024-09-05T19:13:58Z

_data/site_menu.yml

+visualizing:
+  title: Visualizing infrastructure


Hm I'm not sure "visualizing" is how I'd describe this section. It does include viewing inventory but also e.g. reconfiguring_a_vm_disk.md, refreshing_instances_and_images.md, removing_a_datastore.md, creating_a_vm_snapshot.md, etc...

If anything I'd call this "Inventory" or "Managing Inventory", @Fryguy wdyt?

Oh actually that's what the section used to be called, https://github.com/ManageIQ/manageiq-documentation/pull/1806/files#diff-46686079121737af3636a6d1c95d842fc981118049ec6ece21ce578576eebd50L71

Oh I see, I can make the top level heading Managing inventory.

jrafanie · 2024-09-05T19:14:52Z

Ok, this is the before... I think I can imagine what it will look like:

qahmed1998 · 2024-09-05T19:15:40Z

The changes in this PR include, adding new top level headings, moving topics from one heading to another and adding topics which existed but were not part of the ToC. The ToC changes that are in this PR currently aligns with the downstream (AIOps) ToC.

agrare · 2024-09-05T19:17:05Z

_data/site_menu.yml

+      desc: "How to create a service for virtual machine provisioning"
+    - title: Assigning a Custom Analysis Profile to a Virtual Machine
+      path: "/docs/reference/latest/assigning_custom_analysis_profile_to_vm/index.html"
+      desc: "How to assign custom analysis profile to a virtual machine"


I don't know that most of these fall under "Administration", I do think administration for backup&restore or something like creating local users but these are all more related to managing inventory IMO.

Good point. I don't know how to word it but one is administration of the application and one is using the application.

Perhaps a high level "using" section with categories...

Using

Authentication...

Automation

All of the provisioning, service, etc.

Scripting actions ...

Policy

Monitoring, alerts, reporting...

Policies and Profiles guide

Manage Infra and Inv.

Managing Providers...

Configuration

Assigning a Custom Analysis Profile...

Deployment planning guide

...

Administration

Appliance backup/restore

installation

upgrading
...

Note, I would prefer we move things one at a time if we can't have a good visual before/after screenshots. Ideally, each commit changes one thing and the PR changes aren't too much so it's easy to review and get merged. Anything that "feels" like it's a separate change should probably be done in followup PRs so the high level reorganization can go in first.

I can make changes to each big heading (section) in a single commit. With regards to Installing, Upgrading, It will make sense for it to be its own heading and not be under Administration. Administration should contain stuff that can be done by a user once application is installed.

@jrafanie @agrare For the following, Should these go under Configuration or Managing inventory?

Provisioning Virtual Machines and Hosts

Service Provisioning Using an Orchestration Template

Creating a Service in for Virtual Machine Provisioning

Provisioning Virtual Machines and Hosts

Service Provisioning Using an Orchestration Template

Creating a Service in for Virtual Machine Provisioning

I think they would go in using -> automation

agrare · 2024-09-05T19:19:03Z

The ToC changes that are in this PR currently aligns with the downstream (AIOps) ToC.

Okay it seems like some items might be in the wrong place there then also so lets put them in the best place upstream first ™️ and go from there

qahmed1998 · 2024-09-05T19:20:25Z

The ToC changes that are in this PR currently aligns with the downstream (AIOps) ToC.

Okay it seems like some items might be in the wrong place there then also so lets put them in the best place upstream first ™️ and go from there

Yeah sounds good to me.

_data/site_menu.yml

agrare · 2024-09-05T19:30:49Z

NOTE I don't see Automation Management Providers in the existing TOC, can we add under Managing Providers similar to Configuration Providers

qahmed1998 · 2024-09-05T19:32:05Z

NOTE I don't see Automation Management Providers in the existing TOC, can we add under Managing Providers similar to Configuration Providers

Do you have the URL/path of the file/content?

agrare · 2024-09-05T19:36:31Z

https://www.manageiq.org/docs/reference/latest/managing_providers/#automation-management-providers

Added Podified and Appliance categories for "Installing"

qahmed1998 · 2024-09-06T20:44:13Z

Okay so from our discussions in Slack, this is what we have as updated ToC.

Installing

Upgrading

Using

General Configuration
Monitoring, alerts, reporting
Policies and Profiles Guide
Managing Infrastructure and Inventory
Managing Providers and its sub-topics
Provisioning Virtual Machines and Hosts
Scripting Actions in ManageIQ
Creating a Service in for Virtual Machine Provisioning
Service Provisioning Using an Orchestration Template
Managing controls (seems the most suitable name to me as a heading)
- Monitoring, alerts, reporting
- Policies and Profiles Guide
Assigning a Custom Analysis Profile to a Virtual Machine

Administering Infrastructure Management

Authentication
Backup and Restore (appliances)
Deployment planning guide
High Availability Guide
Appliance Hardening Guide

Defining integrations

AWS CloudFormation and OpenStack Heat
ServiceNow

APIs

REST API

Reference

Capabilities Matrix
Methods available for automation

Troubleshooting (same as it is)

qahmed1998 · 2024-09-06T20:44:57Z

Any final adjustments or am I good to make this as the ToC in the PR?

qahmed1998 · 2024-09-09T20:00:11Z

Updated ToC as we discussed. Please review.

Updated the ToC
Added Automation Management Providers topic in ToC
Changed description of a topic
Added Chargeback topic in ToC

_data/site_menu.yml

qahmed1998 · 2024-09-10T19:47:54Z

@jrafanie @Fryguy are we good to merge?

_data/site_menu.yml

qahmed1998 · 2024-09-11T14:08:10Z

Hi Joe, I have addressed your comments.

miq-bot · 2024-09-11T14:10:36Z

Checked commits qahmed1998/manageiq-documentation@3079587~...2557ad9 with ruby 3.1.5, rubocop 1.56.3, haml-lint 0.51.0, and yamllint
1 file checked, 1 offense detected

**

💣 💥 🔥 🚒 - Linter/Yaml - missing config files

jrafanie

Looks good to me. It's hard to see the layout in this format but I think all of the concerns have been addressed.

Fryguy · 2024-09-11T16:34:44Z

This PR broke the build

https://github.com/ManageIQ/manageiq-documentation/actions/runs/10814819288/job/30002189898#step:5:232

Psych::SyntaxError: (/tmp/manageiq-documentation/_data/site_menu.yml): mapping values are not allowed in this context at line 7 column 17
/tmp/manageiq-documentation/Rakefile:10:in `block in <top (required)>'
/opt/hostedtoolcache/Ruby/2.7.8/x64/bin/bundle:23:in `load'
/opt/hostedtoolcache/Ruby/2.7.8/x64/bin/bundle:23:in `<main>'
Tasks: TOP => build
(See full trace by running task with --trace)

Fryguy · 2024-09-11T16:41:24Z

Should be fixed by #1812

jrafanie · 2024-09-11T17:24:45Z

Weird it passed in the PR. 😕

_data/site_menu.yml

Fryguy · 2024-09-11T18:24:20Z

This PR also "broke" the user reference page - https://github.com/ManageIQ/manageiq.org/blob/master/site/docs/reference/index.md?plain=1

I wonder if instead of hardcoding the sections we can more dynamically build it up. Even so, the {{}} stuff won't work there because it's dynamically built.

jrafanie · 2024-09-11T19:47:02Z

This PR also "broke" the user reference page - https://github.com/ManageIQ/manageiq.org/blob/master/site/docs/reference/index.md?plain=1

I wonder if instead of hardcoding the sections we can more dynamically build it up. Even so, the {{}} stuff won't work there because it's dynamically built.

@qahmed1998 see above

Updated ToC

3079587

Added following additional topics to ToC: - Creating a Service in for Virtual Machine Provisioning - Service Provisioning Using an Orchestration Template - Assigning a Custom Analysis Profile to a Virtual Machine

qahmed1998 changed the title ~~Updated ToC~~ Updated ToC for entire ManageIQ + added already existing topics within ToC Aug 26, 2024

Fryguy assigned jrafanie, Fryguy and agrare Aug 28, 2024

Fryguy added the enhancement label Aug 28, 2024

jrafanie reviewed Sep 5, 2024

View reviewed changes

agrare reviewed Sep 5, 2024

View reviewed changes

_data/site_menu.yml Outdated Show resolved Hide resolved

agrare reviewed Sep 5, 2024

View reviewed changes

jrafanie reviewed Sep 5, 2024

View reviewed changes

_data/site_menu.yml Show resolved Hide resolved

Updated Installing section

7e652df

Added Podified and Appliance categories for "Installing"

qahmed1998 added 2 commits September 9, 2024 15:52

minor update to description

aa6fef9

Added "Chargeback" topic

ce92f02

jrafanie reviewed Sep 9, 2024

View reviewed changes

_data/site_menu.yml Outdated Show resolved Hide resolved

jrafanie reviewed Sep 9, 2024

View reviewed changes

_data/site_menu.yml Outdated Show resolved Hide resolved

jrafanie reviewed Sep 9, 2024

View reviewed changes

_data/site_menu.yml Outdated Show resolved Hide resolved

qahmed1998 added 2 commits September 9, 2024 16:45

Update site_menu.yml

bde49f2

update to description

35ccb40

jrafanie mentioned this pull request Sep 10, 2024

Drop rss remnants ManageIQ/manageiq#23180

Merged

2 tasks

jrafanie reviewed Sep 10, 2024

View reviewed changes

_data/site_menu.yml Outdated Show resolved Hide resolved

jrafanie reviewed Sep 10, 2024

View reviewed changes

_data/site_menu.yml Show resolved Hide resolved

Removed ManageIQ Management Engine

2557ad9

jrafanie approved these changes Sep 11, 2024

View reviewed changes

jrafanie merged commit 4eda9ef into ManageIQ:master Sep 11, 2024
2 checks passed

jrafanie assigned jrafanie and unassigned jrafanie, Fryguy and agrare Sep 11, 2024

Fryguy mentioned this pull request Sep 11, 2024

Fix indenting issue in site_menu #1812

Merged

Fryguy reviewed Sep 11, 2024

View reviewed changes

_data/site_menu.yml Show resolved Hide resolved

This was referenced Sep 17, 2024

Fixed ToC issue #1813

Merged

Updated user reference page ManageIQ/manageiq.org#1189

Merged

Updated ToC for entire ManageIQ + added already existing topics within ToC #1806

Updated ToC for entire ManageIQ + added already existing topics within ToC #1806

Conversation

qahmed1998 commented Aug 22, 2024 • edited Loading

Fryguy commented Aug 26, 2024

Fryguy commented Aug 26, 2024 • edited Loading

qahmed1998 commented Aug 26, 2024

Fryguy commented Aug 28, 2024

qahmed1998 commented Sep 5, 2024

jrafanie commented Sep 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qahmed1998 commented Sep 5, 2024 • edited Loading

agrare commented Sep 5, 2024

qahmed1998 commented Sep 5, 2024

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jrafanie commented Sep 5, 2024

qahmed1998 commented Sep 5, 2024 • edited Loading

Choose a reason for hiding this comment

jrafanie Sep 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

qahmed1998 Sep 5, 2024 • edited Loading

Choose a reason for hiding this comment

qahmed1998 Sep 5, 2024 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

agrare commented Sep 5, 2024

qahmed1998 commented Sep 5, 2024

agrare commented Sep 5, 2024

qahmed1998 commented Sep 5, 2024

agrare commented Sep 5, 2024

qahmed1998 commented Sep 6, 2024 • edited Loading

qahmed1998 commented Sep 6, 2024

qahmed1998 commented Sep 9, 2024

qahmed1998 commented Sep 10, 2024

qahmed1998 commented Sep 11, 2024

miq-bot commented Sep 11, 2024

jrafanie left a comment

Choose a reason for hiding this comment

Fryguy commented Sep 11, 2024 • edited Loading

Fryguy commented Sep 11, 2024

jrafanie commented Sep 11, 2024

Fryguy commented Sep 11, 2024

jrafanie commented Sep 11, 2024

qahmed1998 commented Aug 22, 2024 •

edited

Loading

Fryguy commented Aug 26, 2024 •

edited

Loading

qahmed1998 commented Sep 5, 2024 •

edited

Loading

qahmed1998 commented Sep 5, 2024 •

edited

Loading

jrafanie Sep 5, 2024 •

edited

Loading

qahmed1998 Sep 5, 2024 •

edited

Loading

qahmed1998 Sep 5, 2024 •

edited

Loading

qahmed1998 commented Sep 6, 2024 •

edited

Loading

Fryguy commented Sep 11, 2024 •

edited

Loading