From 9201cf03ca4d3971a22b64c8587a22313aa30102 Mon Sep 17 00:00:00 2001 From: Lsnaathorst1 <149484172+Lsnaathorst1@users.noreply.github.com> Date: Wed, 11 Dec 2024 09:41:42 +0000 Subject: [PATCH] 108 readme join up with dfercreate project and update to be md files (#123) * First draft of extra README information, needs formatting and editing still * Updating formatting * Updates to text * Adding link to Markdown Guide * Adding info on create_project function * Updates to correct typos etc * Removing 'applicable to your project' * Adding link to the new readme template * Correcting capitilisation on dfeR --- RAP/rap-statistics.qmd | 37 ++++++++++++++++++++++++++++++------- 1 file changed, 30 insertions(+), 7 deletions(-) diff --git a/RAP/rap-statistics.qmd b/RAP/rap-statistics.qmd index 5b604f0..fd8a466 100644 --- a/RAP/rap-statistics.qmd +++ b/RAP/rap-statistics.qmd @@ -1040,7 +1040,7 @@ You might be thinking that it would be nice if there was software that could hel **What does this mean?** -A README is a text file (.txt) that introduces and explains a project. It contains information that is required to understand what the project is about and how to use it. +A README is a markdown file (.md) that introduces and explains a project. It contains information that is required to understand what the project is about and how to use it. Markdown (.md) files are used for READMEs because they support formatting and render nicely on platforms like GitHub and Azure DevOps, meaning that users can see them on the main page of the repository. You can find guidance on basic markdown syntax on the [Markdown Guide](https://www.markdownguide.org/basic-syntax/){target="_blank" rel="noopener noreferrer"}. **Why do it?** @@ -1048,13 +1048,36 @@ It's an easy way to answer questions that your audience will likely have regardi **How to get started** -As a starting point, you should aim to have as many of the following sections as are applicable to your project: +For new projects, you can use the create_project function in dfeR. Set create_publication_proj to TRUE to create a pre-populated project with a custom folder structure, including a [README template](https://github.com/dfe-analytical-services/dfeR/blob/main/README_template.md). You can find more information on this in the [dfeR reference](https://dfe-analytical-services.github.io/dfeR/reference/create_project.html). -- Introduction -- Requirements (access, software, skills/knowledge) -- How to use -- How to contribute -- Contact details +If you are creating your own README for existing projects, you should include all of the sections listed below: + +**Introduction** + +- Purpose: briefly explain the purpose of the code. +- Overview: Provide a high-level summary of the contents and structure of the repository. + +**Requirements** + +- Access: Detail any permissions or access needed to use the repository at the top of this section, e.g. access to specific SQL databases. This is crucial for enabling new users to use the repository. +- Skills/knowledge: Outline the required skills or knowledge, such as familiarity with specific packages in R, or SQL. +- Version control/Renv: State how version control is managed and whether Renv is being used. + +**Getting started** + +- Setup instructions: Provide step-by-step instructions on how to set up the environment, including installing dependencies. +- Data input/output: Describe the expected input data and where it can be found, as well as what output should be expected from the code. + +**How to run and update** + +- Running the code: Explain how users can best run the code, for example by running a run all script. +- Updating guidelines: Outline the process for updating and contributing to the repository, including specific scripts and lines where updates are frequently needed. Describe how to get changes reviewed. +- Issue reporting: Explain how to report issues or suggest improvements. This could be through issues if using GitHub, boards in Azure DevOps or by emailing the team. + +**Contact details** + +- Main contacts: List the names and contact information of people who maintain the repository. +- Support channels: Provide any information on how to get support, such as email addresses or teams channels. The [Self-assessment tool](https://github.com/dfe-analytical-services/publication-self-assessment-copy){target="_blank" rel="noopener noreferrer"} and the [QA app](https://github.com/dfe-analytical-services/dfe-published-data-qa){target="_blank" rel="noopener noreferrer"} give two examples of readme files structured like this.