Proposal: include code examples for other languages

[frankieroberto]

Context

The GOV.UK Design System website has always included code examples in both HTML and Nunjucks. However, whilst Nunjucks is used by the GOV.UK Prototype Kit, very few services use it in production. Instead, most services use a different language or framework, and either generate the HTML manually, or rely upon a 'port' of the Nunjucks components into their framework.

Some of these 'ports' have now been well-maintained over several years, have complete coverage of all components, and are used by dozens of services across multiple government departments.

Including code examples for these languages could help with several objectives:

• improve the accessibility and usability of services by bringing the technical examples on how to use the components in a language together with the wider guidance on them
• improve discoverability of the ports, so that teams do not accidentally duplicate work by starting a new one for the same language from scratch
• bring more developers to the GOV.UK Design System website, helping to reduce perception of it being purely a design resource
• reduce the need for teams to maintain separate websites detailing how to use each of the components in a particular framework, which can end up either skipping the guidance or duplicating content

How it could work

The GOV.UK Design System team could decide some criteria for which ports should be included in this way. The criteria could include things like:

1. having been maintained for over x years
2. used in production by over y services from at least z organisations
3. at least xx% of components included

Once these criteria are met, the team maintaining the port could contribute the code examples for each component example, making sure that the example generates the same HTML as the existing example.

The examples could then be shown using additional tab links under the examples:

Clicking on them would reveal the code, as well some text making clear that the example uses a port maintained by a different team or community:

In addition, there could be some mention of the ports on the Production page - however any detailed guidance on how to install and set up the port could still be hosted elsewhere, either on a separate website or the README for that port on GitHub.

As an initial trial, the first port added in this way could be the Ruby on Rails port - see pull request #3538

Alternatives

The alternative would likely be for ports to maintain parallel websites detailing how to use each component, and for these to be only linked to from the Community resources page.

Another possibility is for the core GOV.UK Design System team to take on ownership of some of the existing ports (or create new ones). However this would likely require additional resource.

[querkmachine]

My main, initial concerns are around long-term maintenance and governance of how we would do this.

What do we do if a port developer doesn't maintain the code examples for their port? Does the DS team then have to start monitoring what port developers are doing? Do we remove the examples if they don't get updated in a timely manner?

How much grace period do we provide between a new feature being added to Frontend → feature being implemented in port → port example in DS documentation being added, before we consider it outdated?

How do we guarantee that the HTML the example would generate actually does match the HTML shown?

There's also a question of how appropriate it is to 'endorse' ports that are entirely out of the Design System team's hands, and which may not be maintained by a government employee. That can cause administrative headaches if one tried to fundraise or generate profit from their port somehow.

All very hypothetical at the moment, I know, but feels like something that needs a bit of pondering from a processes point of view. A pretty neat idea, otherwise!

[frankieroberto]

@querkmachine all good questions!

What do we do if a port developer doesn't maintain the code examples for their port? Does the DS team then have to start monitoring what port developers are doing? Do we remove the examples if they don't get updated in a timely manner?

The existing community resources page has some contribution criteria which could be re-used for this - but perhaps being included as code examples ought to be a slightly higher bar? 🤔

How much grace period do we provide between a new feature being added to Frontend → feature being implemented in port → port example in DS documentation being added, before we consider it outdated?

The existing criteria suggest 3 months, although I’m not sure how easy that is to validate on an ongoing basis? Feels like a reasonable benchmark though?

How do we guarantee that the HTML the example would generate actually does match the HTML shown?

I suspect this is mainly done manually at the moment, by the different port authors. I think there has been some attempt by authors to automate testing this by using the HTML test fixtures within govuk-frontend - but from memory, issues which don’t affect functional output like whitespace or the need to add extra data attributes or hidden input fields can make it tricky. Might be worth re-exploring though!

There's also a question of how appropriate it is to 'endorse' ports that are entirely out of the Design System team's hands, and which may not be maintained by a government employee. That can cause administrative headaches if one tried to fundraise or generate profit from their port somehow.

The existing criteria include "has a clear owner" and "is not being charged for or used to promote a private business". I’m not sure how many are maintained by government employees vs contractors vs outsourced agencies vs a mix of all? Perhaps a criteria around having an open source licence would help protect against this?

Ultimately I guess it’s for teams to decide which libraries to include in their production code, and to best manage the risks around that. There’s some existing guidance in the Technology code of practice too around using open source too which may help?

The question of non-endorsement is tricky too. The GOV.UK Prototype Kit has a similar dilemma when listing hosting services.

All very hypothetical at the moment, I know, but feels like something that needs a bit of pondering from a processes point of view. A pretty neat idea, otherwise!

🙌