Update GitLab UI form builder docs per reviewer feedback

doc/development/fe_guide/haml.md

@@ -6,19 +6,31 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 # HAML
 
-[HAML](https://haml.info/) is the [Ruby on Rails](https://rubyonrails.org/) template that GitLab uses.
+[HAML](https://haml.info/) is the [Ruby on Rails](https://rubyonrails.org/) template language that GitLab uses.
 
 ## GitLab UI form builder
 
-[GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/) is a Vue component library that conforms to the [Pajamas design system](https://design.gitlab.com/). A lot of these components rely on JavaScript and therefore can only be used in Vue but some of the simpler components (checkboxes, radio buttons, form inputs) can be used in HAML by applying the correct CSS classes to the elements. A custom [Ruby on Rails form builder](https://gitlab.com/gitlab-org/gitlab/-/blob/7c108df101e86d8a27d69df2b5b1ff1fc24133c5/lib/gitlab/form_builders/gitlab_ui_form_builder.rb) exists to help use GitLab UI components in HAML.
+[GitLab UI](https://gitlab-org.gitlab.io/gitlab-ui/) is a Vue component library that conforms
+to the [Pajamas design system](https://design.gitlab.com/). Most of these these components
+rely on JavaScript and therefore can only be used in Vue.
 
-### How to use the GitLab UI form builder
+However, some of the simpler components (checkboxes, radio buttons, form inputs) can be
+used in HAML by applying the correct CSS classes to the elements. A custom
+[Ruby on Rails form builder](https://gitlab.com/gitlab-org/gitlab/-/blob/7c108df101e86d8a27d69df2b5b1ff1fc24133c5/lib/gitlab/form_builders/gitlab_ui_form_builder.rb) exists to help use GitLab UI components in HAML.
 
-1. Change `form_for` to `gitlab_ui_form_for`
-1. Change `f.check_box` to `f.gitlab_ui_checkbox_component`
-1. Remove `f.label` and instead pass the label as the second argument in `f.gitlab_ui_checkbox_component`
 
-**Before**
+### Use the GitLab UI form builder
+
+To use the GitLab UI form builder:
+
+1. Change `form_for` to `gitlab_ui_form_for`.
+1. Change `f.check_box` to `f.gitlab_ui_checkbox_component`.
+1. Remove `f.label` and instead pass the label as the second argument in `f.gitlab_ui_checkbox_component`.
+
+
+For example:
+
+- Before:
 
 ```haml
 = gitlab_ui_form_for @group do |f|
@@ -28,14 +40,14 @@ info: To determine the technical writer assigned to the Stage/Group associated w
       = f.label :prevent_sharing_groups_outside_hierarchy, class: 'custom-control-label' do
         %span
           = s_('GroupSettings|Prevent members from sending invitations to groups outside of %{group} and its subgroups.').html_safe % { group: link_to_group(@group) }
-        %p.js-descr.help-text= prevent_sharing_groups_outside_hierarchy_help_text(@group)
+        %p.help-text= prevent_sharing_groups_outside_hierarchy_help_text(@group)
 ```
 
-**After**
+- After:
 
 ```haml
 = gitlab_ui_form_for @group do |f|
-  .form-group
+  .form-group.gl-mb-3
     = f.gitlab_ui_checkbox_component :prevent_sharing_groups_outside_hierarchy,
         s_('GroupSettings|Prevent members from sending invitations to groups outside of %{group} and its subgroups.').html_safe % { group: link_to_group(@group) },
         help_text: prevent_sharing_groups_outside_hierarchy_help_text(@group),
@@ -44,6 +56,11 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 ### Available components
 
+When using the GitLab UI form builder the following components are available for use in HAML.
+
+NOTE:
+Currently only `gitlab_ui_checkbox_component` is available but more components will be added in the future.
+
 #### gitlab_ui_checkbox_component
 
 [GitLab UI Docs](https://gitlab-org.gitlab.io/gitlab-ui/?path=/story/base-form-form-checkbox--default)