thinning the guidance

[r-leyshon]

Re-reading the current state of the guidance, I think it may be that we get some feedback that it's not straight forward and self-contained. Here are a couple of suggestions for us to discuss for a future iteration of the guidance:

• Moving the content under the index sections in the image below to their respective pages. .
• Keeping the pages in the guidance snappy and minimal.
• Moving the additional information under the "open at the end" page into a dedicated 'fit for publishing' checklist page.

The advantage of this is that we can attribute the NHS guidance appropriately while adding the additional checks, considerations and risk assessment guidance into a separate dedicated page.

I appreciate this is a bit opinionated and we should likely discuss this a bit more before I go ahead and implement any change. So I'll try and make an appropriate label...

feel free to tag others who may wish to be involved.

[ethan-moss]

Good points @r-leyshon, thanks!

To build on that, I think we could put a lot of the content in the 'Open at the End' page inside our own version of the NHS' fit for publication checklist. That way, this page would just come down to a flowchart, some top-level description, and a link to the checklist - nice and clear.

I'm recommending this since I think the current page sends mixed messages - having steps written in words, a linked flowchart that doesn't immediately tie in with the words, a link to NHS' fit for publication checklist, plus a set of bullets at the end to extend this checklist, altogether makes the whole process a little unclear for me. Having our own version of that file would also give us the benefit of incorporating learning lessons for recent 'private to public' transitions too (the current content of the page + more things). So could be a win-win!

What are your thoughts? It would be interesting to see what comes out of the wider consultation.

[ColinDaglish]

I agree with lots of what @ethan-moss has said here. We had a chat about it just now and think we can perhaps try to condense it down with some sort of toggle option. We present the high level instruction, with a toggle option to expand info on why, how and what.

[r-leyshon]

I agree with lots of what @ethan-moss has said here. We had a chat about it just now and think we can perhaps try to condense it down with some sort of toggle option. We present the high level instruction, with a toggle option to expand info on why, how and what.

See here for simple code folding solution that plays ball with GitHub flavoured markdown. A quarto compatible version would be great and hopefully already exists.

[ethan-moss]

This snippet works well in quarto based on the link above.

```{=html}
<details>
    <summary>Title 1</summary>
    Content for title one goes here (in markdown)
</details>

<details>
    <summary>Title 2</summary>
    Content for title two goes here (in markdown)
</details>

<details>
    <summary>Title 3</summary>
    Content for title three goes here (in markdown)
</details>

 It renders in the same way as the GitHub markdown!

[ethan-moss]

Quarto's docs doesn't indicate it has a collapse/folding capability for much more than code snippets and call-outs right now.

But, since quarto runs bootstrap, we could use an accordion.

Here is a modified example from the bootstrap docs using Quarto's inline html syntax :

```{=html}
<div class="accordion  id="exampleAccordion">
  <div class="accordion-item ">
    <p class="accordion-header" id="accHeadingOne">
      <button class="accordion-button" type="button" data-bs-toggle="collapse" data-bs-target="#accCollapseOne" aria-expanded="true" aria-controls="accCollapseOne">
        Accordion 1
      </button>
    </p>
    <div id="accCollapseOne" class="accordion-collapse collapse show" aria-labelledby="accHeadingOne" data-bs-parent="#exampleAccordion">
      <div class="accordion-body">
        Accordion 1 content goes here.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <p class="accordion-header" id="accHeadingTwo">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#accCollapseTwo" aria-expanded="false" aria-controls="accCollapseTwo">
        Accordion 2
      </button>
    </p>
    <div id="accCollapseTwo" class="accordion-collapse collapse" aria-labelledby="accHeadingTwo" data-bs-parent="#exampleAccordion">
      <div class="accordion-body">
        Accordion 2 content goes here.
      </div>
    </div>
  </div>
  <div class="accordion-item">
    <p class="accordion-header" id="accHeadingThree">
      <button class="accordion-button collapsed" type="button" data-bs-toggle="collapse" data-bs-target="#accCollapseThree" aria-expanded="false" aria-controls="accCollapseThree">
        Accordion 3
      </button>
    </p>
    <div id="accCollapseThree" class="accordion-collapse collapse" aria-labelledby="accHeadingThree" data-bs-parent="#exampleAccordion">
      <div class="accordion-body">
        Accordion 3 content goes here.
      </div>
    </div>
  </div>
</div>

This works OK in Quarto, and follows Bootstrap's [accessibility recommendations](https://getbootstrap.com/docs/5.1/components/collapse/#accessibility) - Wave does not highlight errors or alerts. But it's a lot of HTML to write and edit... so maintenance would be slightly more complex.

I'm OK with any of the options that have been shared here.

[r-leyshon]

My initial thoughts are that the details tag should do the job, whatever content is in scope of the accordion (images, callouts etc) would hopefully fold on click. Is your consideration of the accordion based on the docs or have you tried it? Is it out of the question to expect data scientists to write in HTML? I quite like it haha! Also, +1 for the HTML code chunk, didn't know that was a thing.

[ethan-moss]

I've tried that bootstrap accordion snippet and it works very well. I've just tried adding images in, and it folds away too. My feeling is anything that we put inside the accordion-body div should fold away nicely.

From a stylistic point of view, my preference would be the accordion since it's much cleaner and clearer when rendered. Haha, it's probably not out of the question, it's just a little more messy to maintain inside a markdown file that's all.

Given the current lack of Quarto capability and the options available to us, I'm happy to go ahead with a HTML accordion approach if it suits others writing these docs too.

[r-leyshon]

agree, accordion it is. Now where are my onions?

[NicciPotts]

Survey feedback #42 covered by this card