Add guidance on deciding how to deliver something

source/guides/how-to-decide-what-to-deliver.html.md

@@ -0,0 +1,64 @@
+---
+title: How to decide what to deliver
+weight: 5
+---
+
+# How to decide what to deliver
+
+The whole GOV.UK Design System product is a multi-faceted service made up of multiple parts including APIs, code and design assets, guidance and community resources. When adding to our product or solving a problem, it is not always obvious how we should deliver whatever we're building for our users.
+
+Use these principles in conjunction with the definitions of things in the product to help decide what form the thing you're working on takes.
+
+To help you decide what to work on and [how to deliver the Design System](./how-we-deliver-the-design-system-to-our-users/) to solve a particular problem, keep these principles in mind.
+
+## Don't decide too early
+
+Making an assumption about the precise form can create expectations for our users and the team which can lead to confusion if we change our minds later.
+
+## It's okay to change your mind
+
+Similar to the previous principle, it’s also fine to change what we’re trying to do as we discover new information. We work in an agile way and should respond appropriately to new information as it arises.
+
+## Sometimes you need more than one thing
+
+There are times when a problem cannot be solved by one thing and you need to deliver additional complementary things to fully achieve what you want.
+
+We have several cases where we've documented a component as well as a pattern applying that component in a whole journey. An example of this is the [Task list component](https://design-system.service.gov.uk/components/task-list/) which describes using the component itself in isolation, as well as the pattern to [Help users to complete multiple tasks](https://design-system.service.gov.uk/patterns/complete-multiple-tasks/) which describes the end-to-end journey of a user completing multiple tasks as part of a service.
+
+If one thing isn't solving the problem then it's okay to expand the scope of what you deliver if you feel that it's necessary.
+
+## Take an MVP approach
+
+Ask yourself what is the minimal effort required to solve the problem at hand. This means we can get it published as quickly as possible. Once it's live, we can be expand and improve as we get new data from our users and their end users.
+
+## If you can avoid new code, do so
+
+New components or changes to components or styles require the most work in a strict 'roles impacted' sense because it means we need to add or change code in GOV.UK Frontend and therefore requires direct involvement from developers. More code also means more for us to maintain. Patterns or guidance are other ways we can affect change that can have a lower impact on the overall team .
+
+A more specific application of this principle is in patterns. If you want to document a new thing that is only made up of existing components and doesn't change the behaviour of those things, then this can be a smaller scale pattern rather than a new component.
+
+## Consider what the user will need to do
+
+The nature of our product as a design system means that users almost always need to take action to make use of anything we add, however the work they need to do varies by what we add. If we can reduce the amount of work our users need to do then we should.
+
+A new component for example requires our users to upgrade to the version of GOV.UK Frontend with that new component and then implement it on their service. A new pattern might require a minimum version of GOV.UK Frontend but typically only requires the user to implement that pattern into their service.
+
+## Adding things are not breaking – changes might be
+
+Part of deciding what to deliver also involves understanding if a change is breaking. A breaking change means that we know at least some users will need to take action for their service to continue functioning, not just to use a new feature.
+
+Keep this in mind when deciding what to deliver. Additions to our library almost always mean that users can upgrade to a new version of GOV.UK Frontend with minimal technical work required because their service can continue working without using the new feature. Changes to existing library items do not always mean users need to make changes themselves but might need to depending on the change. 
+
+The key question to ask is: will this change stop anyone's service from functioning?
+
+Also note that breaking changes do not always mean we cannot do something. There are techniques we can use to manage breaking changes over time to minimise user impact, such as [feature flags](http://../development/feature-flags/).
+
+## Content work is always required
+
+Across all techniques for deciding what to deliver, we always need to add or change guidance in our content spaces. We also need to write documentation and sometimes explain our process and rationale. This could be a small or big piece of work, but it will always need to happen. As a minimum, inform a content designer or technical writer about a piece of work early and ideally involve them in the decision making process on what to deliver.
+
+## Conventions are important
+
+Our design system follows conventions laid out in the definitions of each thing listed in [How we deliver the design system to users](./how-we-deliver-the-design-system-to-our-users/). For example, a component guidance page should always be about a unique component in GOV.UK Frontend and that guidance should be scoped as much as possible to that component's behaviour and how to use it.
+
+Following these conventions lead to a more consistent design system which makes it more predictable and easier to use and maintain. We should try to follow our existing conventions as closely as possible. If we have the choice to not break a convention we should try to follow this path. If we need to break a convention it should be for a good reason.

source/guides/index.html.md

@@ -9,6 +9,7 @@ A collection of 'how to' guides to help you you do a thing.
 
 - [Decision making techniques](./decision-making-techniques/)
 - [How to collect feedback from the community](./how-to-collect-feedback-from-the-community/)
+- [How to decide what to deliver](./how-to-decide-what-to-deliver/)
 - [How to get help from other roles](./get-help-from-other-roles/)
 - [How to purchase something](./how-to-purchase-something/)
 - [How to run a Design System team ceremony or workshop](./how-to-run-a-design-system-team-ceremony-or-workshop/)

source/what-we-do/how-we-deliver-the-design-system-to-our-users.html.md

@@ -0,0 +1,65 @@
+---
+title: How we deliver the design system to our users
+weight: 5
+---
+# How we deliver the design system to our users
+
+The way we provide the different parts of our product each depend on what we are trying to achieve and the work involved.
+
+These include the typical elements that we think most often about as parts of the Design System:
+
+- styles  
+- components  
+- patterns
+
+There’s also many other outputs that can sit within or around the typical elements:
+
+- features and extensions of styles, components and patterns (sometimes called variants)  
+- guidance and documentation
+
+## Styles
+
+Styles make government services look and feel like GOV.UK. They are the foundational design and code elements of GOV.UK Frontend and the wider design system. Examples include [Colour](https://design-system.service.gov.uk/styles/colour/), [Spacing](https://design-system.service.gov.uk/styles/spacing/) and typography, such as our [responsive type scale](https://design-system.service.gov.uk/styles/type-scale/).
+
+These are all strongly tied into the code of GOV.UK Frontend, with the sole exception being [guidance on images](https://design-system.service.gov.uk/styles/images/) which we do not deliver via code but is still important information pertinent to users building services using the design system.
+
+Adding or removing a style would be very rare and require a great deal of work to change it across GOV.UK Frontend and the Design System. Changing styles is more common but still rare. We would need to consider impact across GOV.UK Frontend, to our styles guidance and to our users and how they use those styles in their services.
+
+## Components
+
+Components are reusable parts of a user interface. Using pre-built, core elements allows government teams to build consistent services. Examples include [Buttons](https://design-system.service.gov.uk/components/button/), [Service navigation](https://design-system.service.gov.uk/components/service-navigation/) and [Inset text](https://design-system.service.gov.uk/components/inset-text/).
+
+All component pages in the design system website are tied to technical component code in GOV.UK Frontend, which each include:
+
+- a [Nunjucks](https://mozilla.github.io/nunjucks/) template  
+- a [Sass](https://sass-lang.com/) file  
+- an API documentation file (a [Yaml](https://yaml.org/) file)  
+- a JavaScript file, if the component requires JavaScript and automated tests for the component
+
+Components all add unique code to GOV.UK Frontend. This includes components that rely on other components. For example the [Password input](https://design-system.service.gov.uk/components/password-input/) component imports the text input component and the button component, but adds additional styling and javascript to create the password input.
+
+Therefore it’s expected that if something does not require any additional code and is only made up of existing components, that a new component is not needed.
+
+## Patterns
+
+Patterns are best practice design solutions for specific user-focused tasks and page types.
+
+The scope of the patterns section ranges from single uses of a component such as [how to ask for names](https://design-system.service.gov.uk/patterns/names/), to whole pages in a service such as [confirmation pages](https://design-system.service.gov.uk/patterns/confirmation-pages/), to whole journeys such as [creating accounts](https://design-system.service.gov.uk/patterns/create-accounts/).
+
+Whilst patterns are made up of things from GOV.UK Frontend and will often include example code that can be copied, patterns do not live in GOV.UK Frontend as code like components do and we’d expect not to create any new code solely for a new pattern. This is because we expect patterns to be made up of components only, so a user can make a pattern themselves without needing us to author unique code for them.
+
+There are a couple of instances where patterns are reliant on things outside of GOV.UK Frontend such as the [Step by step pattern](https://design-system.service.gov.uk/patterns/step-by-step-navigation/) which is scoped to the GOV.UK website only, however this still doesn't interact with GOV.UK Frontend.
+
+## Features and extensions of existing styles, components or patterns
+
+Sometimes, a new feature or problem to solve does not need a new library item and instead can be an extension of an existing item. An example of this is the [summary card](https://design-system.service.gov.uk/components/summary-list/#summary-cards), which is a 'feature' of the [Summary list](https://design-system.service.gov.uk/components/summary-list/) component rather than a distinct component which imports the summary list.
+
+There isn't a one-size-fits-all approach to deciding if something similar to an existing part of our library can be extended instead of creating a new thing. An extension can save on the technical weight of GOV.UK Frontend and means that we and our users do not have to maintain one extra thing, but risks making things more complex.
+
+## Guidance and documentation
+
+Another way that we can solve problems is by not providing any new code or pattern guidance at all and instead writing content for our users. This could be technical documentation, a how-to guide or a 'history' document, to name some examples.
+
+This is useful if the problem we’re trying to solve is more around getting users to understand existing parts of the product rather than rolling out a new thing.
+
+Bear in mind that the scope of content work can still vary depending on what it is, ranging from a single page to a whole content journey.  

source/what-we-do/index.html.md.erb

@@ -9,12 +9,40 @@ We maintain the GOV.UK Design System and related tools. For guidance on supporti
 
 ## Our products
 
-### Actively developed
+The design system is principally made up of 3 separate but intersecting artifacts that help us serve our users in different ways.
 
-- [GOV.UK Design System Website] - guidance for making government services consistent with GOV.UK. The code is maintained in the [govuk-design-system GitHub repository].
-- [GOV.UK Frontend] - a code library of GOV.UK Design System components.
-- [GOV.UK Frontend Docs] - Technical documentation for installing and using GOV.UK Frontend. The code is maintained in the [govuk-frontend-docs GitHub repository].
-- [Community backlog] - a backlog of user-submitted component and pattern suggestions for inclusion into the Design System.
+### GOV.UK Frontend
+
+The frontend code package that we publish via [npm (Node Package Manager)](https://www.npmjs.com/). Service teams use this package when building their service to more easily make their services look like GOV.UK and gain access to our styles and components.
+
+We also include APIs which enable our users to:
+
+- manipulate individual components  
+- gain access to and interact with our styles
+
+### GOV.UK Design System
+
+[The GOV.UK Design System website](https://design-system.service.gov.uk/) functions as a directory of everything in GOV.UK Frontend, notably our [styles](https://design-system.service.gov.uk/styles/) and [components](https://design-system.service.gov.uk/components/), as well as [common frontend patterns](https://design-system.service.gov.uk/patterns/) in government services such as form questions and pages.
+
+As a contribution based design system, the website also provides ways that users can interact with us and get involved in contribution or community activities in our [Community section](https://design-system.service.gov.uk/community/).
+
+The website also links out to additional digital government resources such as [ports of GOV.UK Frontend for specific tech stacks](https://design-system.service.gov.uk/community/resources-and-tools/).
+
+### GOV.UK Frontend docs
+
+[The GOV.UK Frontend docs are the technical documentation for GOV.UK Frontend](https://frontend.design-system.service.gov.uk/). This is another guidance website focused on technical documentation rather than as a directory of our design system and a 'brochure' for the product the way that the Design System website is. This contains:
+
+- technical guides for installing and using GOV.UK Frontend  
+- guides for managing frontend architecture and staying up to date  
+- complete API references for our [Sass](https://frontend.design-system.service.gov.uk/sass-api-reference/) and [JavaScript](https://frontend.design-system.service.gov.uk/javascript-api-reference/)
+
+We expect the audience for the Frontend docs to be more technical and at a point in their development process where they're trying to understand how to build something with GOV.UK Frontend.
+
+### Also actively developed
+
+Our team also work on:
+
+- [Community backlog] - a backlog of user-submitted component and pattern suggestions for inclusion into the Design System.  
 - [stylelint-config-gds] - a stylelint configuration for SCSS and CSS files across GDS.
 
 ### Maintenance
@@ -30,17 +58,14 @@ We maintain the GOV.UK Design System and related tools. For guidance on supporti
 
 [Accessible Autocomplete]: https://github.com/alphagov/accessible-autocomplete
 [Community backlog]: https://design-system.service.gov.uk/community/backlog/
-[GOV.UK Design System website]: https://design-system.service.gov.uk/
-[govuk-design-system GitHub repository]: https://github.com/alphagov/govuk-design-system
 [GOV.UK Elements]: http://govuk-elements.herokuapp.com/
 [GOV.UK Frontend]: https://github.com/alphagov/govuk-frontend
-[GOV.UK Frontend Docs]: https://frontend.design-system.service.gov.uk/
-[govuk-frontend-docs GitHub repository]: https://github.com/alphagov/govuk-frontend-docs
 [GOV.UK Frontend Toolkit]: https://github.com/alphagov/govuk_frontend_toolkit
 [GOV.UK Prototype Kit]: https://govuk-prototype-kit.herokuapp.com/docs
 [GOV.UK Template]: http://alphagov.github.io/govuk_template/
 [stylelint-config-gds]: https://github.com/alphagov/stylelint-config-gds
 
-### Future strategy
+## Other pages in this section
 
+- [How we deliver the Design System to our users](./how-we-deliver-the-design-system-to-our-users/)
 - [Where the GOV.UK Design System is heading](./future-of-the-govuk-design-system/)