Aib improve contributing guidance (#203)

* Update CONTRIBUTE.md

* add PR guidance

* Update template-project.md

* fixed accessibility guidance link on CONTRIBUTE.md

* apply review comments

---------

Co-authored-by: warren-davies4 <112185584+warren-davies4@users.noreply.github.com>

Author: amaiaita

CONTRIBUTE.md

@@ -4,27 +4,41 @@ Hi there! We're thrilled that you'd like to contribute to the NHS England Data S
 
 ## Creating an issue
 
-If you think of something worth including, improving, or want to contribute, please [raise an issue on GitHub](https://github.com/nhsengland/datascience/issues).
+If you think of something worth including, improving, or you find a bug, please [raise an issue on GitHub](https://github.com/nhsengland/datascience/issues).
 
 ## Submitting a pull request
 
-If you want to contribute to our resources:
+If you want to contribute to our resources I would recommend using codespaces directly in github to do this. Guidance is as follows: 
+1. If your change constitutes a significant content contribution, before starting with any actual changes, you must go through a content review - follow these [instructions](#content-review)
+2. In the repository [homepage](https://github.com/nhsengland/datascience), click the button on the top left which says 'main', then type the name of the branch you want to create, and press create branch
+   ![image](https://github.com/user-attachments/assets/f6250b49-d5cf-4a65-8b5f-c02145daab77)
+ 
+3. Click the green code button, then Codespaces, then the '+' symbol to create a new codespace on your branch.
+    <img width="1355" alt="Screenshot 2025-03-27 at 14 13 13" src="https://github.com/user-attachments/assets/b68437a3-3f72-467e-8a42-ffb9de7fed29" />
+4. This should automatically launch a codespace, which also creates a local version of the website after a minute or so, which you should be able to access in the ports section at the bottom of the codespace.
+![image](https://github.com/user-attachments/assets/3192cf0a-acc3-4ca3-876a-9e348621459a)
+5. Make any changes you wish to the website here and commit and push as you would in VSCode (guidance specific to project pages and blog can be found below).
+6. Check your changes in the local instance to make sure they arent breaking anything and look as you want them to.
+7. [Submit a pull request][pr]
+
+
+If you insist on doing this locally, follow these steps:
 
 1. [Fork][fork] or clone the repository
-2. Configure and install the dependencies if you want to run the page in your machine, otherwise none.
+2. Configure and install the dependencies if you want to run the page in your machine.
 3. Create a new branch: `git checkout -b my-branch-name`
 4. Make your change
 5. Check how your change looks on our website by hosting the website locally (follow [the steps below](#contribute-to-nhs-england-data-science-website) on how to do this)
 6. Content Review (follow the [instructions](#content-review))
 7. Push to your fork and [submit a pull request][pr]
 
-Your pull request will then be reviewed. You may receive some feedback and suggested changes before it can be approved and your pull request merged.
+Contact someone from [Marketing & Comms Function Team](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=351578724) to review your Pull Request. You may receive some feedback and suggested changes before it can be approved and your pull request merged.
 
-To increase the likelihood of your pull request being accepted:
+**To increase the likelihood of your pull request being accepted:**
 
 - If you are making visual changes, include a screenshot of what the affected element looks like, both before and after.
 - Follow the [style guide][style].
-- Follow the [accessibility guidance][https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=902212969]. The most important aspects are to include alt text for images that convey meaning, and null alt text for decorative images, colour not being the only way to convey any of the meaning in your content, descriptive heading and labels, and images aren't used as text (if you have images that convey text meaning, they should be SVGs), and any links have a descriptive text, not just "click here" or "link".
+- Follow the [accessibility guidance](https://nhsd-confluence.digital.nhs.uk/pages/viewpage.action?pageId=902212969). The most important aspects are to include alt text for images that convey meaning, and null alt text for decorative images, colour not being the only way to convey any of the meaning in your content, descriptive heading and labels, and images aren't used as text (if you have images that convey text meaning, they should be SVGs), and any links have a descriptive text, not just "click here" or "link".
 - Keep your change as focused as possible. If there are multiple changes you would like to make that are not dependent upon each other, consider submitting them as separate pull requests.
 - Write [good commit messages](http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html).
 
@@ -52,7 +66,7 @@ To add a new file to the repository and website:
 
 - Add any files for new pages to the relevant folder in [`docs`](./docs/).
 - Add any images you'll use in the [`docs/images`](./docs/images/) folder.
-- Because this website uses the `awesome-pages` mkdocs addon, we don't need to update the 'nav' in mkdocs.yml - it will happen automatically when the website is built.
+- Add your page to the appropriate place(s) in [`mkdocs.yml`](mkdocs.yml)
 - Don't forget to check that the links, images, headings, and contents are all working correctly on both the website and in the GitHub repo.
 
 The website currently uses the [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/getting-started/) theme. This sets the layout, colour, font, search bar, header, footer, navigation bar and contents. You can follow the documentation to make any changes (e.g. change the [colour scheme](https://squidfunk.github.io/mkdocs-material/setup/changing-the-colors/)) as it is simple to use and also easy to overwrite. There is a separate stylesheet, [extra.css](./docs/stylesheets/extra.css), which is used to overwrite the colours, fonts and some of the sizing for some elements.
@@ -62,14 +76,14 @@ Here is a good [cheat sheet](https://yakworks.github.io/docmark/cheat-sheet/) fo
 
 Prior to making a pull request, ensure that, if the changes involve a change or addition of content (rather than technical or spelling changes) to the site, you have gone through a content review as outlined [here](https://nhsd-confluence.digital.nhs.uk/display/DAT/C&M:+Website+Gateway). This is to ensure that no sensitive or policy content goes into your PR, as whilst PRs aren't live on the website they are still public (as the repo is public).
 
-#### Blog / Article
+### Blog / Article
 
 Creating new articles / blog posts is easy:
 
 - add a markdown file under the [`docs/articles/posts`](./docs/articles/posts) folder.
   - Note, you do not have to add the blog pages to the `mkdocs.yml` - it gets added to the nav bar automatically.
 - add yourself to the [`docs/articles/posts/.authors.yml`], so your face and info appears next to the article.
-- The markdown file should have some metadata at the start, like the below. For more info on these parameters, see the [mkdocs material blog plugin guidance](https://squidfunk.github.io/mkdocs-material/plugins/blog/).
+- The markdown file should have some metadata at the start, like the below. For more info on these parameters, see the [mkdocs material blog plugin guidance](https://squidfunk.github.io/mkdocs-material/plugins/blog/). You can also copy it from another blog to make sure you've got it right.
 
 ```markdown
 ---
@@ -87,6 +101,11 @@ description: >
 ---
 ```
 
+### Project Page 
+
+- Check out the [project template](https://github.com/nhsengland/datascience/blob/aib-improve-contributing-guidance/docs/our_work/template-project.md?plain=1) for how to contribute a project page to the website.
+
+
 ## Resources
 
 - [Contributing to Projects](https://docs.github.com/en/get-started/quickstart/contributing-to-projects)

docs/our_work/template-project.md

@@ -2,13 +2,14 @@
 title: 'TITLE GOES HERE'
 summary: 'ONE LINE SUMMARY GOES HERE'
 origin: 'Skunkworks  (this is for legacy pages mainly, so we know where the work came from)'
-# tags: ['add your tags in here as a list (there is no limit) and remove the comment #','tag 2','tag 3']
+# tags: ['add your tags in here as a list (there is no limit) and remove the comment #','tag 2','tag 3' See below for guidance on choosing tags.]
 ---
-[comment]: <> When deciding your tags, look at the [tag ontology](https://nhsengland.github.io/datascience/our_work/tags/) and try and choose a tag per category and not add any new tags. If you think new tags are required because the existing ones don't match your project, let someone in the Comms & Marketing Function Team know. 
 
 [comment]: <> The metadata block above is used to make the title, the tags, and the first block of "quote text" just beneath the title
 
-[comment]: <> Make a nice visual abstract for your project, or show some key result, which makes the impact of your work clear - imagine your audience is an educated observer from the health system
+[comment]: <> When deciding your tags, look at the [tag ontology](https://nhsengland.github.io/datascience/our_work/tags/) and try and choose a tag per category and not add any new tags. If you think new tags are required because the existing ones don't match your project, let someone in the Comms & Marketing Function Team know. 
+
+[comment]: <> Make a nice visual abstract for your project, or show some key result, which makes the impact of your work clear - imagine your audience is an educated observer from the health system. Every project page needs to have at least one image so that it can get pulled for the homepage.
 [![Alt text for the image](../images/<add your age to the image folder and put the file name here>)](<add a relevant URL if you have one - people like to click images!>)
 
 [comment]: <> Add some description about your project - keep it punchy, focussing on the benefits, anything new, and only the most important parts of the methods, particularly anything which might interest people.
@@ -17,8 +18,8 @@ People often have this problem - we used data science to make the solution. We w
 
 ## Results
 
-[comment]: <> Add some description of the key results - again keep them punchy, and in real units that people can understand if possible. This is where we get across the impact. It might be that the image describes this, in which case reference that.
-by automating the problem area described above, we were able to save £xxx / so many hours of doctor / patient / staff time. The diagram above shows how impactful this was.
+[comment]: <> Add some description of the key results - again keep them punchy, and in real units that people can understand if possible. This is where we get across the impact. It might be that the image describes this, in which case reference that. 
+E.g.: by automating the problem area described above, we were able to save £xxx / so many hours of doctor / patient / staff time. The diagram above shows how impactful this was.
 
 Output|Link