govuk-design-system
govuk-design-system copied to clipboard
alphagov
Improve Nunjucks variables and options content
Our content about Nunjucks variables and options (for example the template variables table) needs improving because the table format is getting overstretched.
The issues are:
- there's too much content for table cells
- we can't link to particular variables
- we can't easily add code examples
We should also look at whether to standardise on either 'variables' or 'options'.
Some thoughts as an external user:
I reckon this should be first class content on the page, rather than tied to each example and collapsed by default.
I tend to skim the examples to see what's possible - but often common features aren't shown in the examples. It feels counterintuitive to go to 'options' as for an example you don't want to see what else it can do.
It feels like useful options can get hidden in here. There's a disparity often between what's shown as examples vs what the options offer. As an example, I wanted to see if the file upload component supported a hint - I went to the component page, skimmed the examples, did command-f to search for 'hint' - nothing came up.
Related, we could have general guidance on using macros. Like for example content can normally be text (with html escaped so it appears like <p>this</p> on the page) or html so it actually becomes html (useful for formatting).
Agree! It's interesting that we don't give general option guidance even when an example is based on actually using an option. For example the start button example is fundamentally 'use isStartButton: true if you want this start button' (if you're using Nunjucks), but we don't mention that specifically in the guidance above the example. You have to infer it from the code/options.
Definitely agree with bringing out the options as main content too. Both for searchability as @edwardhorsford mentioned, and to avoid the confusing and potentially misleading duplication inside each example.
User reported here that they missed the link for the Nunjucks options table altogether: https://github.com/alphagov/govuk-design-system/issues/1422#issuecomment-741838630
There has been an instance today where we've wanted to link directly to a list of Nunjucks parameters for a component, but it wasn't clear how to do this.
As another thought, we occassionally encounter support issues wherein a user is trying to use Nunjucks parameters introduced in a later version of Frontend than the one they're using.
Although we keep archive versions of documentation for major versions of Frontend, we don't do so for feature releases, which may also introduce new parameters. The version of Frontend these parameters were added in is not typically documented.
When we decide to improve how we display Nunjucks parameter info, we may want to add the ability to 'tag' which versions specific parameters were introduced in.