dfe-analytical-services / dfe-analytical-services/analysts-guide

[Other]: Reducing and tidying content in RAP principles section

Open
#240 1 comment 0 reactions 0 assignees View on GitHub
Dominant language
R
Stars
6
Forks
9
PR merge metrics
No merged PRs in 30d

Description

### Description

Following the [RAP for analysis principles PR](https://github.com/dfe-analytical-services/analysts-guide/pull/138), it was agreed that the RAP principles text needs reducing in length and content to make it easier to navigate. This was originally written with the intention of the unit using it and we should rewrite to reflect that this is now a webpage used across the organisation and make it easier and quicker to navigate.

Feedback from Lara to be considered:

_The pages laying out all the RAP principles seem really long and hard to navigate to me. There is a lot within each principle's section and it's not very clear where each principle starts and begins. Some of the sub-sub-headings are larger than the sub-headings which is a bit counter intuitive, and for example the "How to get started" bits are very long for some principles with a lot in there - I would say far too much and it’s potentially overwhelming. Personally I would either (the first option being my preference):
a) Keep it as one page for each of the 3 core principles, with a section for each individual principle (so as it's currently it set out). But have just one or two concise paragraphs for each of "What does this mean?", "Why do it?" and "How to get started" for every principle. i.e. cutting out a lot of what's in there now._

Cam suggests we could investigate using co-pilot or a custom Databricks LLM model with context for a preferred writing style to offer quick redrafting suggestions as a starting point.

We should also investigate splitting up the 'writing code' principle, as Menna suggested. This core principle is huge in comparison to the other two.

Screenshot shows an example of the text to be cut down:

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.