Skip to content

Commit

Permalink
Add the content checklist (#193)
Browse files Browse the repository at this point in the history 
- added to the content toolkit index
- new page of content
  • Loading branch information
@miaodon
miaodon authored May 21, 2024
1 parent 01ff04f commit 2779b1c
Show file tree
Hide file tree
Showing 2 changed files with 270 additions and 0 deletions.
6 changes: 6 additions & 0 deletions src/content-toolkit/index.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -12,6 +12,12 @@ related: "content-toolkit"
- steps to publishing good content
- get help reviewing your content

## [Use the content checklist](/content-toolkit/use-the-content-checklist) {.govuk-heading-m .govuk-!-margin-bottom-1}

- how to write less
- make your content easy to read
- meet GOV.UK and Defence standards

## [Audit your content](/content-toolkit/audit-your-content) {.govuk-heading-m .govuk-!-margin-bottom-1}

- why you need to audit content in Defence
Expand Down
264 changes: 264 additions & 0 deletions src/content-toolkit/use-the-content-checklist.njk
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,264 @@
{% extends "layouts/guidance.njk" %}

{% set title = "Use the content checklist" %}
{% set description = "When you write content for Defence, use this checklist to help you meet GOV.UK and Defence content standards. " %}

{% block body %}

<div class="govuk-width-container">

<div class="govuk-breadcrumbs">

<ol class="govuk-breadcrumbs__list">
<li class="govuk-breadcrumbs__list-item">
<a class="govuk-breadcrumbs__link" href="{{ '/' | url }}">Home</a> > <a class="govuk-breadcrumbs__link" href="{{ '/content' | url }}">Content</a> > <a class="govuk-breadcrumbs__link" href="{{ '/content-toolkit' | url }}">Content toolkit</a>
</li>
</ol>

</div>

</div>

<div class="govuk-width-container">

<div class="govuk-main-wrapper">

<div class="govuk-grid-row">
<div class="govuk-grid-column-two-thirds">
<h1 class="govuk-heading-xl">Use the content checklist</h1>
</div>
</div>

<div class="govuk-grid-row">

<div class="govuk-grid-column-one-third position-sticky">

</div>

<div class="govuk-grid-column-two-thirds">

<p class="govuk-body">Use this checklist to help you write clear content for people across Defence. This checklist supports GOV.UK and Defence standards.</p>


{# <h2 class="govuk-heading-l" id="What you need to do">What you need to do</h2> #}

{% set htmlAccordion1 %}
<p class="govuk-body">Before writing anything, you need to check if similar content is:</p>

<ul class="govuk-list govuk-list--bullet">
<li>published on GOV.UK</li>
<li>published on the intranet or in other Defence publications</li>
<li>being created by other teams in Defence</li>
</ul>

<p class="govuk-body">Creating duplicate or slightly different content in lots of places confuses people and costs more to manage. It is better to link to existing content when you can.</p>
<p class="govuk-body">If you need to make changes to existing content, contact the service or platform owner.</p>

{% endset %}

{% set htmlAccordion2 %}

<p class="govuk-body">Content in Defence often includes too much information. This makes it hard for people to understand information quickly and easily. </p>
<p class="govuk-body">Before writing any content, define what people need to know to understand something or do a task. Then, only include content that helps them. Start by telling people what has changed or what they need to do.</p>
<p class="govuk-body">Write the user needs at the top of your draft. Review every sentence against the user needs and delete what people do not need. If some users need more information, include links to it.</p>
<p class="govuk-body">Find more <a href="https://defence-service-manual.netlify.app/content/write-less-content/">guidance on writing less content</a>.</p>

{% endset %}

{% set htmlAccordion3 %}
<p class="govuk-body">Active language makes it clear who needs to do something. </p>
<p class="govuk-body">Write in the present tense and address the reader as 'you'. For example, instead of 'The form needs to be submitted' use 'You need to submit the form'.</p>
<p class="govuk-body">You can refer to your organisation as 'we'. For example, instead of 'A confirmation email will be sent', use 'We will send you a confirmation email'.</p>
<p class="govuk-body">Find more <a href="https://www.gov.uk/guidance/content-design/writing-for-gov-uk#:~:text=Writing%20to%20GOV.-,UK,-style">guidance on GOV.UK style</a>.</p>

{% endset %}

{% set htmlAccordion4 %}
<p class="govuk-body">Write like you are in a conversation with someone. Use the shortest word or phrase you can. For example, choose:<p>

<ul class="govuk-list govuk-list--bullet">
<li>'use' instead of 'utilise'</li>
<li>'because' instead of 'as a consequence of'</li>
<li>'to' instead of 'in order to' </li>
</ul>

<p class="govuk-body">When you write for experts, you can use the words they use but think about people who are new to Defence. For example, instead of 'interoperability' you can use 'work together', 'act together' or 'integrate'.</p>
<p class="govuk-body">You can <a href="https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#words-to-avoid:~:text=a%20brand%20name.-,Words%20to%20avoid,-Plain%20English%20is">check GOV.UK words to avoid</a>.</p>


{% endset %}

{% set htmlAccordion5 %}
<p class="govuk-body">People read titles to check if the content is important to their role. Create titles that are short, clear and descriptive.</p>
<p class="govuk-body">Make sure your title:</p>

<ul class="govuk-list govuk-list--bullet">
<li>is less than 65 characters long</li>
<li>tells people what they need to do</li>
<li>starts with a verb, when possible</li>
<li>includes words used in online searches</li>
</ul>

<p class="govuk-body">For example, instead of 'Training course for cyber security awareness' use 'Apply for cyber security training'. </p>

{% endset %}

{% set htmlAccordion6 %}

<p class="govuk-body">Try to avoid using acronyms. This can be difficult in Defence. There are many acronyms that mean different things.</p>

<p>If you need to use an acronym, make sure you write it out in full the first time people see it. For example: Anyone from the Air Logistics Command (ALC) can apply.</p>

{% endset %}

{% set htmlAccordion7 %}
<p class="govuk-body">Short sentences are not just easier for people with dyslexia or anyone who struggles to read. Everyone in Defence needs to understand content quickly.</p>
<p class="govuk-body">Following GOV.UK style, your sentences cannot be longer than 25 words. Ideally, your sentences should be shorter.</p>
<p class="govuk-body">To make sentences shorter, you can:</p>

<ul class="govuk-list govuk-list--bullet">
<li>delete words that are not needed</li>
<li>add full stops to break up sentences</li>
<li>use bullets and numbered lists</li>
</ul>

<p class="govuk-body">Find more <a href="https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#:~:text=Upper%20case.-,Bullet%20points%20and%20steps,-You%20can%20use">guidance on using bullets and lists</a>.</p>

{% endset %}

{% set htmlAccordion8 %}
<p class="govuk-body">People scan content to find information that is relevant to them.</p>
<p class="govuk-body">It is difficult to scan a long block of words. You need to break up your content with useful headers.</p>
<p class="govuk-body">In your headers, speak directly to the user and keep the language active. Good examples on GOV.UK include:</p>

<ul class="govuk-list govuk-list--bullet">
<li>What has changed</li>
<li>What you need to do</li>
<li>When you need to to this</li>
</ul>

<p class="govuk-body">Keep the content under each header short. It is fine to have a single paragraph.</p>

{% endset %}

{% set htmlAccordion9 %}
<p class="govuk-body">Reading what you have written out loud helps you check that your content flows well.</p>
<p class="govuk-body">Sometimes, swapping the order of words can make a sentence easier to read. If there is too much jargon, you will trip over it. If you need to take a breath, the sentence is too long.</p>

{% endset %}

{% set htmlAccordion10 %}
<p class="govuk-body">Use the publishing process to help you create good content for people in Defence. The process includes understanding user needs and ways to check your content.</p>
<p class="govuk-body">Find out <a href="/content-toolkit/follow-the-publishing-process">more about the publishing process</a>.</p>

{% endset %}


{{ component('accordion', {
classes: 'govuk-!-margin-bottom-0',
id: 'accordion-standards',
items: [
{
heading: {
text: '1. Check what is already published'
},
content: {
html: htmlAccordion1
}
},
{
heading: {
text: '2. Only write what people need'
},
content: {
html: htmlAccordion2
}
},
{
heading: {
text: '3. Use active language'
},
content: {
html: htmlAccordion3
}
},
{
heading: {
text: '4. Choose simple and familiar words'
},
content: {
html: htmlAccordion4
}
},
{
heading: {
text: '5. Give your content a strong title'
},
content: {
html: htmlAccordion5
}
},
{
heading: {
text: '6. Write out acronyms the first time'
},
content: {
html: htmlAccordion6
}
},
{
heading: {
text: '7. Keep sentences short'
},
content: {
html: htmlAccordion7
}
},
{
heading: {
text: '8. Break up content with headers'
},
content: {
html: htmlAccordion8
}
},
{
heading: {
text: '9. Read your content out loud'
},
content: {
html: htmlAccordion9
}
},
{
heading: {
text: '10. Follow the publishing process'
},
content: {
html: htmlAccordion10
}
}
]
}) }}

<br><br>

<h3 class="govuk-heading-m">Related guidance</h3>

<ul class="govuk-list">
<li><a href="https://servicemanual.digital.mod.uk/content/">Create user-centred content in Defence</a></li>
<li><a href="https://www.gov.uk/guidance/content-design/writing-for-gov-uk">Content design: planning, writing and managing content</a></li>
<li><a href="https://www.gov.uk/guidance/style-guide">GOV.UK style guide</a></li>
</ul>

<p class="govuk-body govuk-body--secondary govuk-!-font-size-14 govuk-!-margin-top-8 govuk-!-margin-bottom-0">Published May 2024</p>

</div>

</div>

</div>

</div>

{% endblock %}

0 comments on commit 2779b1c

Please sign in to comment.