Update hierarchy of user guides (#6950)

Adds a new category for guiding pages both on hiring staff and jobseekers sides.
DFE-Digital · Jul 11, 2024 · c586413 · c586413
1 parent aa0eb5a
commit c586413
Show file tree

Hide file tree

Showing 34 changed files with 318 additions and 54 deletions.
diff --git a/app/components/dashboard_component/dashboard_component.html.slim b/app/components/dashboard_component/dashboard_component.html.slim
@@ -3,14 +3,14 @@
     .govuk-grid-column-full
       = govuk_notification_banner title_text: "Important", classes: "govuk-notification-banner govuk-!-margin-top-0 govuk-!-margin-bottom-5" do |banner|
         - banner.with_heading(text: t("jobs.dashboard.non-teaching-roles-banner.heading"))
-        p.govuk-body = govuk_link_to(t("jobs.dashboard.non-teaching-roles-banner.link_text"), "/get-help-hiring/how-to-list-non-teaching-roles")
+        p.govuk-body = govuk_link_to(t("jobs.dashboard.non-teaching-roles-banner.link_text"), "/get-help-hiring/how-to-create-job-listings-and-accept-applications/how-to-list-non-teaching-roles")
 
   .govuk-grid-row
     .govuk-grid-column-three-quarters
       .help-guide--mobile.help-guide--border-bottom
         h2.govuk-heading-m = t("jobs.dashboard.how_to_accept_job_applications_guide.title")
         = govuk_link_to(t("jobs.dashboard.how_to_accept_job_applications_guide.link_text"),
-                        post_path(section: "get-help-hiring", post_name: "accepting-job-applications-on-teaching-vacancies"),
+                        post_path(section: "get-help-hiring", subcategory: "get-help-applying-for-your-teaching-role", post_name: "accepting-job-applications-on-teaching-vacancies"),
                         class: "govuk-link--no-visited-state")
         | .
       span.govuk-caption-l = @organisation.name
@@ -53,7 +53,7 @@
         .help-guide--desktop class="govuk-!-margin-top-4"
           h2.govuk-heading-m = t("jobs.dashboard.how_to_accept_job_applications_guide.title")
           = govuk_link_to(t("jobs.dashboard.how_to_accept_job_applications_guide.link_text"),
-                          post_path(section: "get-help-hiring", post_name: "accepting-job-applications-on-teaching-vacancies"),
+                          post_path(section: "get-help-hiring", subcategory: "get-help-applying-for-your-teaching-role", post_name: "accepting-job-applications-on-teaching-vacancies"),
                           class: "govuk-link--no-visited-state")
           | .
     #vacancy-results class=grid_column_class
@@ -128,6 +128,6 @@
         .help-guide--desktop
           h2.govuk-heading-m = t("jobs.dashboard.how_to_accept_job_applications_guide.title")
           = govuk_link_to(t("jobs.dashboard.how_to_accept_job_applications_guide.link_text"),
-                          post_path(section: "get-help-hiring", post_name: "accepting-job-applications-on-teaching-vacancies"),
+                          post_path(section: "get-help-hiring", subcategory: "get-help-applying-for-your-teaching-role", post_name: "accepting-job-applications-on-teaching-vacancies"),
                           class: "govuk-link--no-visited-state")
           | .
diff --git a/app/controllers/posts_controller.rb b/app/controllers/posts_controller.rb
@@ -1,15 +1,25 @@
 class PostsController < ApplicationController
   def index
-    @posts = MarkdownDocument.all(params[:section])
+    @subcategories = get_subcategories(params[:section])
+  end
+
+  def subcategory
+    @posts = MarkdownDocument.all(params[:section], params[:subcategory])
+    render :subcategory
   end
 
   def show
-    @post = MarkdownDocument.new(params[:section], params[:post_name])
+    @post = MarkdownDocument.new(params[:section], params[:subcategory], params[:post_name])
     not_found unless @post.exist?
   end
 
   private
 
+  def get_subcategories(section)
+    content_dir = Rails.root.join("app", "views", "content", section)
+    Dir.children(content_dir)
+  end
+
   def set_headers
     response.set_header("X-Robots-Tag", "index, nofollow")
   end

diff --git a/app/helpers/guiding_pages_helper.rb b/app/helpers/guiding_pages_helper.rb
@@ -0,0 +1,12 @@
+module GuidingPagesHelper
+  ALWAYS_CAPITALIZE_WORDS = ["england"].freeze
+
+  def format_title(subcategory)
+    words = subcategory.downcase.split("-")
+    words.map!.with_index do |word, index|
+      word.capitalize! if index.zero? || ALWAYS_CAPITALIZE_WORDS.include?(word)
+      word
+    end
+    words.join(" ")
+  end
+end
diff --git a/app/services/markdown_document.rb b/app/services/markdown_document.rb
@@ -1,22 +1,29 @@
 class MarkdownDocument
   include Comparable
 
-  attr_reader :section, :post_name
+  attr_reader :section, :subcategory, :post_name
 
-  def initialize(section, post_name)
+  def initialize(section, subcategory, post_name)
     @section = section
+    @subcategory = subcategory
     @post_name = post_name
     parse if exist?
   end
 
-  def self.all(section)
-    dir_path = Rails.root.join("app", "views", "content", section)
+  def self.all(section, subcategory)
+    dir_path = Rails.root.join("app", "views", "content", section, subcategory)
 
     Dir.children(dir_path).map do |file_name|
-      new(section, file_name.remove(".md"))
+      new(section, subcategory, file_name.remove(".md"))
     end
   end
 
+  def self.all_subcategories(section)
+    dir_path = Rails.root.join("app", "views", "content", section)
+
+    Dir.children(dir_path)
+  end
+
   def title
     @front_matter["title"]
   end
@@ -68,6 +75,6 @@ def file_content
   end
 
   def file_path
-    Rails.root.join("app", "views", "content", @section, "#{@post_name}.md")
+    Rails.root.join("app", "views", "content", @section, @subcategory, "#{@post_name}.md")
   end
 end
diff --git a/...job-applications-on-teaching-vacancies.md → ...job-applications-on-teaching-vacancies.md b/...job-applications-on-teaching-vacancies.md → ...job-applications-on-teaching-vacancies.md
diff --git a/...reating-the-perfect-teacher-job-advert.md → ...reating-the-perfect-teacher-job-advert.md b/...reating-the-perfect-teacher-job-advert.md → ...reating-the-perfect-teacher-job-advert.md
diff --git a/...-hiring/how-to-list-non-teaching-roles.md → ...cations/how-to-list-non-teaching-roles.md b/...-hiring/how-to-list-non-teaching-roles.md → ...cations/how-to-list-non-teaching-roles.md
diff --git a/...ng/how-mats-can-use-teaching-vacancies.md → ...nt/how-mats-can-use-teaching-vacancies.md b/...ng/how-mats-can-use-teaching-vacancies.md → ...nt/how-mats-can-use-teaching-vacancies.md
diff --git a/...how-to-approve-access-for-hiring-staff.md → ...how-to-approve-access-for-hiring-staff.md b/...how-to-approve-access-for-hiring-staff.md → ...how-to-approve-access-for-hiring-staff.md
diff --git a/...ing/how-to-request-organisation-access.md → ...unt/how-to-request-organisation-access.md b/...ing/how-to-request-organisation-access.md → ...unt/how-to-request-organisation-access.md
diff --git a/...ck-ways-to-find-the-right-teaching-job.md → ...ck-ways-to-find-the-right-teaching-job.md b/...ck-ways-to-find-the-right-teaching-job.md → ...ck-ways-to-find-the-right-teaching-job.md
diff --git a/...nd-a-teaching-role-at-the-right-school.md → ...nd-a-teaching-role-at-the-right-school.md b/...nd-a-teaching-role-at-the-right-school.md → ...nd-a-teaching-role-at-the-right-school.md
@@ -41,6 +41,6 @@ Have a look at the [Education staff wellbeing charter](https://www.gov.uk/guidan
 The charter is a shared commitment to protect, promote and enhance the wellbeing of school staff. 
 Schools will approach wellbeing differently, so even if they aren’t signed up to the charter, it’s a good idea to ask how staff are supported.
 
-
 ## Search for roles
-[Search for roles on Teaching Vacancies now.](https://teaching-vacancies.service.gov.uk/jobs?keyword=&location=)
+<a href="https://teaching-vacancies.service.gov.uk/jobs?keyword=&location=" class="govuk-button">Search for roles on Teaching Vacancies now.</a>
+
diff --git a/...w-to-approach-a-teaching-job-interview.md → ...w-to-approach-a-teaching-job-interview.md b/...w-to-approach-a-teaching-job-interview.md → ...w-to-approach-a-teaching-job-interview.md
@@ -28,7 +28,7 @@ Study the school’s website to get a sense of what the school is like. Prepare
 ## 4. Know about statutory guidance on safeguarding
 If you have not had any experience of dealing with a safeguarding issue yourself, you must still be able to talk about what you would do. Think of some possible scenarios and explain how you would address them.
 
-[Statutory guidance for schools and colleges on safeguarding children and safer recruitment on GOV.UK](https://www.gov.uk/government/publications/keeping-children-safe-in-education--2)
+[Statutory guidance for schools and colleges on safeguarding children and safer recruitment on GOV.UK](https://www.gov.uk/government/publications/keeping-children-safe-in-education--2).
 
 ## 5. Ask the panel questions
 This shows your interest and gives you the opportunity to inform your decision about the role. You could ask:

diff --git a/...ow-to-write-teacher-personal-statement.md → ...ow-to-write-teacher-personal-statement.md b/...ow-to-write-teacher-personal-statement.md → ...ow-to-write-teacher-personal-statement.md
@@ -5,10 +5,10 @@ meta_description: Expert advice on what to include in your personal statement wh
 date_posted: 15/03/2022
 category_tags: apply
 ---
+![A teacher talking to students while they're working.](/content-assets/jobseeker-guides/How_to_write_your_teacher_training_personal_statement.jpg)
 
 Your personal statement is your first opportunity to show the school you’re a great fit for the job, and gets you closer to being shortlisted for an interview. The more you show how your skills and interests match the school’s ethos and values, the better. We've spoken to a range of teachers to get their top tips for success.
 
-
 ## What experience do you have?
 Schools want to hear about your trainee experience with different subjects, key stages, types of school, and working with a range of pupils.
 
@@ -32,4 +32,5 @@ Schools will also want to know how you overcome challenges.
 Set yourself apart by showing how your hobbies and achievements could contribute to the wider school community. Could you run an after school club or organise school trips?
 
 ## Search for roles
-[Search for roles on Teaching Vacancies now.](https://teaching-vacancies.service.gov.uk/jobs?keyword=&location=)
+<a href="https://teaching-vacancies.service.gov.uk/jobs?keyword=&location=" class="govuk-button">Search for roles on Teaching Vacancies now.</a>
+
diff --git a/...re-for-a-teaching-job-interview-lesson.md → ...re-for-a-teaching-job-interview-lesson.md b/...re-for-a-teaching-job-interview-lesson.md → ...re-for-a-teaching-job-interview-lesson.md
diff --git a/...teaching-job-application-in-five-steps.md → ...teaching-job-application-in-five-steps.md b/...teaching-job-application-in-five-steps.md → ...teaching-job-application-in-five-steps.md
diff --git a/...urn-to-england-after-teaching-overseas.md → ...urn-to-england-after-teaching-overseas.md b/...urn-to-england-after-teaching-overseas.md → ...urn-to-england-after-teaching-overseas.md
@@ -46,6 +46,6 @@ Get ready to apply by:
 
 You can search for a teaching job in England through the government’s official Teaching Vacancies service.
 
-Set up job alerts so you don’t miss out on new roles
+Set up job alerts so you don’t miss out on new roles.
 
 [Search for roles on Teaching Vacancies now.](https://teaching-vacancies.service.gov.uk/jobs?keyword=&location=)
diff --git a/...nt/jobseeker-guides/return-to-teaching.md → ...teaching-in-england/return-to-teaching.md b/...nt/jobseeker-guides/return-to-teaching.md → ...teaching-in-england/return-to-teaching.md
@@ -10,7 +10,7 @@ category_tags: apply
 
 If you’re thinking about returning to teaching, or if you’re qualified to teach but have never taught in a state school in England, support is available.
 
-If you trained to teach in the UK and are a UK citizen currently working abroad, find out about [returning to England to teach.](https://teaching-vacancies.campaign.gov.uk/return-to-england-after-teaching-overseas/)
+If you trained to teach in the UK and are a UK citizen currently working abroad, find out about [returning to England to teach.](https://teaching-vacancies.service.gov.uk/jobseeker-guides/return-to-england-after-teaching-overseas)
 
 ## Get back into teaching
 Returning to teaching might be easier than you think.
@@ -32,7 +32,7 @@ The Department for Education (DfE) has been taking action to help schools suppor
 * enabling [flexible working opportunities](https://www.gov.uk/government/collections/flexible-working-resources-for-teachers-and-schools) 
 * putting in place [behaviour hubs](https://behaviourhubs.co.uk/)
 
-Teaching is a diverse and inclusive profession with many networks that can help you in your teaching career, including [WomenEd](https://womened.com/), [BAMEed](https://www.bameednetwork.com/), [LGBTed](https://lgbted.uk/) and [DisabilityEd](https://twitter.com/disability_ed)
+Teaching is a diverse and inclusive profession with many networks that can help you in your teaching career, including [WomenEd](https://womened.com/), [BAMEed](https://www.bameednetwork.com/), [LGBTed](https://lgbted.uk/) and [DisabilityEd](https://twitter.com/disability_ed).
 
 ## Get a return to teaching adviser
 If you have [qualified teacher status (QTS)](https://www.gov.uk/guidance/qualified-teacher-status-qts), you could be eligible for a [return to teaching adviser.](https://getintoteaching.education.gov.uk/landing/return-to-teaching-advisers)
@@ -58,7 +58,7 @@ If you qualified as a teacher outside the UK, you must have qualified teacher st
 ## Find your perfect teaching job
 Every school has its own culture and values so it’s useful to consider what’s important to you when searching for a teaching job.
 
-You can [find out more about how to find a teaching role at the right school.](https://teaching-vacancies.campaign.gov.uk/find-a-teaching-role-at-the-right-school/)
+You can [find out more about how to find a teaching role at the right school.](https://teaching-vacancies.service.gov.uk/jobseeker-guides/find-a-teaching-role-at-the-right-school)
 
 ## Get help applying for a teaching job
 
@@ -67,9 +67,9 @@ If you’ve found a teaching job which looks right for you, help make it yours w
 Find out how to:
 
   * [write a teacher personal statement](https://teaching-vacancies.service.gov.uk/jobseeker-guides/how-to-write-teacher-personal-statement)
-  * [write a great teaching job application in 5 steps](https://teaching-vacancies.campaign.gov.uk/get-help-applying-for-teacher-jobs/write-a-great-teaching-job-application/)
-  * [approach a teaching job interview](https://teaching-vacancies.campaign.gov.uk/get-help-applying-for-teacher-jobs/how-to-approach-a-teaching-job-interview/)
-  * [prepare for a teaching interview lesson](https://teaching-vacancies.campaign.gov.uk/get-help-applying-for-teacher-jobs/prepare-for-a-teaching-interview-lesson/)
+  * [write a great teaching job application in 5 steps](https://teaching-vacancies.service.gov.uk/jobseeker-guides/write-a-great-teaching-job-application-in-five-steps)
+  * [approach a teaching job interview](https://teaching-vacancies.service.gov.uk/jobseeker-guides/how-to-approach-a-teaching-job-interview)
+  * [prepare for a teaching interview lesson](https://teaching-vacancies.service.gov.uk/jobseeker-guides/prepare-for-a-teaching-job-interview-lesson)
 
 When you’re ready, you can search for a job on [Teaching Vacancies.](https://teaching-vacancies.service.gov.uk/)
 

diff --git a/app/views/home/index.html.slim b/app/views/home/index.html.slim
@@ -8,7 +8,7 @@
     p.govuk-body = t(".description")
     p.govuk-body = t(".personal_statement_section.description_html",
                      personal_statement_guide_link: govuk_link_to(t(".personal_statement_section.link_text"),
-                                                    posts_path(section: "jobseeker-guides"),
+                                                    post_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role", post_name: "how-to-write-teacher-personal-statement"),
                                                     class: "govuk-link--no-visited-state"))
   .govuk-grid-column-one-quarter
     h2.govuk-heading-m = t(".jobseeker_section.title")
@@ -17,7 +17,7 @@
       .govuk-body class="govuk-!-margin-bottom-3" = govuk_link_to t("buttons.view_account"), jobseeker_root_path, class: "govuk-link--no-visited-state"
     - else
       p.govuk-body = t(".jobseeker_section.signed_out.description_html")
-      = govuk_button_link_to(t(".jobseeker_section.signed_out.link_text.sign_in"), new_jobseeker_session_path, class: "govuk-!-margin-bottom-2")
+      = govuk_button_link_to(t("buttons.sign_in"), new_jobseeker_session_path, class: "govuk-!-margin-bottom-2")
       p.govuk-body = t(".jobseeker_section.signed_out.create_account_html", create_account_link: govuk_link_to(t(".jobseeker_section.signed_out.link_text.create_account"), new_jobseeker_registration_path, class: "govuk-link--no-visited-state"))
 
   .govuk-grid-column-one-quarter

diff --git a/app/views/jobseekers/job_applications/build/personal_statement.html.slim b/app/views/jobseekers/job_applications/build/personal_statement.html.slim
@@ -21,7 +21,7 @@
       h3.govuk-heading-m = t(".personal_statement_guide.title")
       p.govuk-body = t(".personal_statement_guide.description_mobile")
       = govuk_link_to(t(".personal_statement_guide.link_text"),
-                      post_path(section: "jobseeker-guides", post_name: "how-to-write-teacher-personal-statement"),
+                      post_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role", post_name: "how-to-write-teacher-personal-statement"),
                       class: "govuk-link--no-visited-state")
 
     - if job_application.vacancy.personal_statement_guidance.present?
@@ -46,5 +46,5 @@
       h3.govuk-heading-m = t(".personal_statement_guide.title")
       p.govuk-body = t(".personal_statement_guide.description_desktop")
       = govuk_link_to(t(".personal_statement_guide.link_text"),
-                      post_path(section: "jobseeker-guides", post_name: "how-to-write-teacher-personal-statement"),
+                      post_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role", post_name: "how-to-write-teacher-personal-statement"),
                       class: "govuk-link--no-visited-state")
diff --git a/app/views/layouts/_footer.html.slim b/app/views/layouts/_footer.html.slim
@@ -16,7 +16,7 @@
               li.govuk-footer__list-item
                 = link_to t("footer.search_teaching_vacancies"), root_url, class: "govuk-footer__link"
               li.govuk-footer__list-item
-                = link_to t("footer.return_to_teaching"), "https://teaching-vacancies.campaign.gov.uk/return-to-teaching/", class: "govuk-footer__link"
+                = link_to t("footer.return_to_teaching"), post_path(section: "jobseeker-guides", subcategory: "return-to-teaching-in-england", post_name: "return-to-teaching"), class: "govuk-footer__link"
               li.govuk-footer__list-item
                 = tracked_link_to(t("footer.international_teacher_advice_link_text"), "https://getintoteaching.education.gov.uk/non-uk-teachers", class: "govuk-footer__link", link_type: :international_teacher_advice_link_footer)
               li.govuk-footer__list-item
@@ -26,19 +26,19 @@
                   = link_to t("nav.jobseeker_sign_in"), new_jobseeker_session_path, class: "govuk-footer__link"
               li.govuk-footer__list-item
                 = link_to t("nav.personal_statement"),
-                          post_path(section: "jobseeker-guides", post_name: "how-to-write-teacher-personal-statement"),
+                          post_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role", post_name: "how-to-write-teacher-personal-statement"),
                           class: "govuk-footer__link"
               li.govuk-footer__list-item
-                = link_to t("nav.find_a_teaching_job_at_the_right_school"),
-                          post_path(section: "jobseeker-guides", post_name: "find-a-teaching-job-at-the-right-school"),
+                = link_to t("nav.find_a_teaching_role_at_the_right_school"),
+                          post_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role", post_name: "find-a-teaching-role-at-the-right-school"),
                           class: "govuk-footer__link"
               li.govuk-footer__list-item
                 = link_to t("nav.return_to_england_after_teaching_overseas"),
-                          post_path(section: "jobseeker-guides", post_name: "return-to-england-after-teaching-overseas"),
+                          post_path(section: "jobseeker-guides", subcategory: "return-to-teaching-in-england", post_name: "return-to-england-after-teaching-overseas"),
                           class: "govuk-footer__link"
                 li.govuk-footer__list-item
-                = link_to t("nav.return_to_teaching"),
-                          post_path(section: "jobseeker-guides", post_name: "return-to-teaching"),
+                = link_to t("nav.get_help_applying_for_your_teaching_role"),
+                          subcategory_path(section: "jobseeker-guides", subcategory: "get-help-applying-for-your-teaching-role"),
                           class: "govuk-footer__link"
 
       .govuk-grid-column-one-half

diff --git a/app/views/posts/index.html.slim b/app/views/posts/index.html.slim
@@ -10,5 +10,5 @@
     h1.govuk-heading-xl = t(".#{params[:section]}.title")
     p.govuk-body = t(".#{params[:section]}.description")
     ul.govuk-list
-      - @posts.sort.each do |post|
-        li = govuk_link_to(post.title, post_path(section: post.section, post_name: post.post_name))
+      - @subcategories.each do |subcategory|
+        li = govuk_link_to(format_title(subcategory), subcategory_path(section: params[:section], subcategory: subcategory))
diff --git a/app/views/posts/show.html.slim b/app/views/posts/show.html.slim
@@ -5,6 +5,7 @@
   nav aria-label="breadcrumb" role="navigation"
     = govuk_breadcrumbs breadcrumbs: { t("breadcrumbs.home") => root_path,
                                        params[:section].titleize.capitalize => posts_path(section: params[:section]),
+                                       params[:subcategory].titleize.capitalize => subcategory_path(section: params[:section], subcategory: params[:subcategory]),
                                        @post.title => "" }
 
 .govuk-grid-row.post

diff --git a/app/views/posts/subcategory.html.slim b/app/views/posts/subcategory.html.slim
@@ -0,0 +1,16 @@
+- formatted_subcategory = format_title(params[:subcategory])
+- content_for :page_title_prefix, formatted_subcategory.to_s
+- content_for :page_description, "All posts under the subcategory: #{formatted_subcategory}"
+
+- content_for :breadcrumbs do
+  = govuk_breadcrumbs breadcrumbs: { t("breadcrumbs.home") => root_path,
+    params[:section].titleize.capitalize => posts_path(section: params[:section]),
+    formatted_subcategory => "" }
+
+.govuk-grid-row
+  .govuk-grid-column-full
+    h1.govuk-heading-xl = formatted_subcategory.to_s
+    p.govuk-body = t(".#{params[:section]}.#{params[:subcategory]}")
+    ul.govuk-list
+      - @posts.sort.each do |post|
+        li = govuk_link_to(post.title, post_path(section: post.section, subcategory: post.subcategory, post_name: post.post_name))
diff --git a/app/views/publishers/new_features/reminder.html.slim b/app/views/publishers/new_features/reminder.html.slim
@@ -8,5 +8,5 @@
       = t(".page_title")
     p.govuk-body
       = t(".content")
-    = open_in_new_tab_link_to(t(".how_applications_work_link"), post_path(section: "get-help-hiring", post_name: "accepting-job-applications-on-teaching-vacancies"), class: "govuk-body")
+    = open_in_new_tab_link_to(t(".how_applications_work_link"), post_path(section: "get-help-hiring", subcategory: "get-help-applying-for-your-teaching-role", post_name: "accepting-job-applications-on-teaching-vacancies"), class: "govuk-body")
     = govuk_button_to t("buttons.reminder_continue"), organisation_jobs_path, class: "govuk-!-margin-top-8"