This repo functions well as a collection of job descriptions, but it has two shortcomings
1) it is difficult to compare job descriptions (for consistency) by clicking around in the GitHub UI
2) many of the JDs have content in common, which we should be able to standardise & template
This pull request makes a step towards fixing both those things by incorporating just the JDs for software development into the GOV.UK Tech Docs template, and putting that in a subfolder alongside the existing Markdown files. Once we've standardised the Software Developer JDs we can remove those old Markdown files and keep the Markdown files we've got in here.
Then we can do the same for other professions.
Note that the GOV.UK tech docs template uses plain Markdown files; there is no barrier to entry for those who would rather view things on GitHub, or would like to contribute. Indeed, there are instant benefits: GOV.UK tech docs provides a friendly web UI for viewing (and reviewing!) JDs. As the navigation component of GOV.UK Tech Docs parses headings in Markdown files, it immediately points up inconsistencies in how we're describing roles:
Because Middleman (the static site generator which powers GOV.UK Tech Docs) supports templating and partials, this change enables us to work to pull out common parts of JDs. I have a vague idea that we could somehow mark bits of a given JD that come from a template, so it's extremely clear what's boilerplate and what's not.
Out of scope for this PR
deploying this site — for now it's necessary to follow the instructions in the README to run locally. I don't think there's any reason not to publish this somewhere publicly accessible, but happy to be guided by DfE policy on that.
making any amendments to the JDs themselves. I ran everything through markdownlint, but apart from that they're untouched. Hopefully that makes this change less controversial.
Interesting decisions to make about the JDs
what are the standard headings we want?
what is the standard "about DfE" boilerplate? (and is it always the same?)
should we aim to have EO/HEO/SEO/G7/G6 roles for each discipline (obviously this doesn't make sense for e.g. architects, but eg right now "Software developers" have 2 SEO roles, DevOps have no G6, etc)
This repo functions well as a collection of job descriptions, but it has two shortcomings
1) it is difficult to compare job descriptions (for consistency) by clicking around in the GitHub UI 2) many of the JDs have content in common, which we should be able to standardise & template
This pull request makes a step towards fixing both those things by incorporating just the JDs for software development into the GOV.UK Tech Docs template, and putting that in a subfolder alongside the existing Markdown files. Once we've standardised the Software Developer JDs we can remove those old Markdown files and keep the Markdown files we've got in here.
Then we can do the same for other professions.
Note that the GOV.UK tech docs template uses plain Markdown files; there is no barrier to entry for those who would rather view things on GitHub, or would like to contribute. Indeed, there are instant benefits: GOV.UK tech docs provides a friendly web UI for viewing (and reviewing!) JDs. As the navigation component of GOV.UK Tech Docs parses headings in Markdown files, it immediately points up inconsistencies in how we're describing roles:
Because Middleman (the static site generator which powers GOV.UK Tech Docs) supports templating and partials, this change enables us to work to pull out common parts of JDs. I have a vague idea that we could somehow mark bits of a given JD that come from a template, so it's extremely clear what's boilerplate and what's not.
Out of scope for this PR
markdownlint
, but apart from that they're untouched. Hopefully that makes this change less controversial.Interesting decisions to make about the JDs