Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

108 readme join up with dfercreate project and update to be md files #123

37 changes: 30 additions & 7 deletions RAP/rap-statistics.qmd
Original file line number Diff line number Diff line change
Expand Up @@ -1040,21 +1040,44 @@ 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?**

It's an easy way to answer questions that your audience will likely have regarding how to install and use your project and also how to collaborate with you.

**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.

Expand Down
Loading