USWDS-Site: Add note about settings with dot notation #2122

amyleadem · 2023-06-06T16:43:54Z

Summary

Added a section about configuring settings that are described using dot notation.

Additionally, reordered the "What to include in your configuration" content and the compilation error note in order to improve flow.

⚠️ We need to update the changelog date before merge.

Related issue

Closes #2116

Preview link

Preview link: Settings page

Problem statement

On our site, we use dot notation to describe settings that are nested inside a settings map. For example: we refer to $background-color-settings.responsive in our utilities documentation. This can lead to confusion when users try to configure this setting, because you cannot include the following in your USWDS configuration:

@use "uswds-core" with (
  $background-color-settings.responsive: true,
);

Instead, the configuration would need to look like this:

@use "uswds-core" with (
  $background-color-settings: (
      responsive: true,
    )
);

Solution

Adding a note about dot notation next to the settings map configuration will help guide users to understand how to configure a setting described in dot notation.

Testing and review

Confirm that the note conveys intended meaning and is placed in the appropriate location on site.
Confirm there are no spelling or grammatical errors.

amyleadem · 2023-06-06T16:48:44Z

pages/documentation/settings.md

+{:.site-note.radius-bottom-0}
+**Note:** We use dot notation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.
+
+{:.site-note.margin-top-0.radius-top-0}


Note: I contemplated creating a style that would visually merge two site-note items that directly follow each other, with the goal of allowing multiple elements to combine into a single site note. However, I opted for utility classes instead because of the chance that we might want two separate site-notes adjacent siblings.

mahoneycm

Love this change! I was worried about users misunderstanding this before. Thanks for taking the time to come up with this!

!

bonnieAcameron · 2023-06-06T18:16:49Z

pages/documentation/settings.md

 ```

+{:.site-note.radius-bottom-0}
+**Note:** We use dot notation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.


I think we should describe the environment in which we use the dot notation as well as potentially link out to a resource that tells them more about it. So then it would be like:

Suggested change

**Note:** We use dot notation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.

**Note:** We use [dot notation](https://builtin.com/data-science/dot-notation) in most of our documentation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.

@bonnieAcameron I like this suggestion! Wondering if a simpler link might be more appropriate for this since users don't really need to understand any of the whys or hows for using it - they just need to know what it is and that we use it in our docs. A possible substitute: (Chose MDN because we use it as a source elsewhere on the site)

https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/Property_accessors

Happy to defer to your expertise.

Thanks @amyleadem! I guess my only concern is that they don't know that they don't need to know the hows and whys. The MDN link provides a circular definition (using a word to define itself). Is there another source we regularly reference?

Note:
After an offline discussion with @bonnieAcameron, I have added this link as a resource in case users want to learn more about what dot notation is.

I looked at MDN and other more expected resources, but could not find a simple definition.
~~⚠️ @thisisdano, is it ok to use a resource like this?~~

Update: This question is no longer relevant because we removed the link altogether.

bonnieAcameron

Hi @amyleadem Amy! I made a comment with suggestions. Let me know what you think.

…t-notation

- Make small tweaks to dot notation copy

- Make this a section easier to find via screen readers, etc

amyleadem · 2023-06-15T17:53:59Z

@bonnieAcameron I have added a resource link as we discussed and made a few small copy tweaks in a6cf618 and cfdaaf4.

I decided to add an h4 header in 789c472 with the idea that it might make the section easier to find for users with screen readers, since it explains an important piece of our docs.

Let me know what you think!

bonnieAcameron

Looks great, Amy!

…t-notation

mejiaj

Some concerns with this guidance:

Note placement

It seems too detached from a realistic example. The note mentioned about $background-color-settings can seem confusing.

From what I understand, we're adding this guidance to explain the use of dot notation in the table right? If so, it'd make sense to move it closer.

Dot notation guidance

Is there any way we can paraphrase or provide our own explanation? I'd rather avoid another potential 404/403 issue if/when the author decides to modify the URL.

Note formatting

I noticed this morning our site notes are inconsistent and created this issue for it USWDS-Site - Bug: Inconsistent site notes #2164. This adds another style/variant to it. Could we revert back to using the standard formatting?

…t-notation

- Moved 'What to include' up to provide basic config info sooner - Mover error note higher to be closer to related content - Moved dot notation section closer to settings tables - Improved clarity of content in dot notation section - Removed site note styles to accommodate longer text and code sample

amyleadem · 2023-07-10T16:00:57Z

pages/documentation/settings.md

+{: .site-note }
+**Note:** If you receive the error `This module was already loaded, so it can't be configured using "with"`, confirm that all your declared variables exist in the [settings tables](#general-settings) and try compiling again.


Note
Moved this error note up higher because it seemed directly related to this section

amyleadem · 2023-07-10T16:02:38Z

pages/documentation/settings.md

 Note that the settings variables in this module inform both general theme and component customizations.

-### Configuring settings maps
+### What to include in your configuration


Note
Reorganized this content a bit to help with flow. The page started to feel a bit disjointed after a few rounds of additions (including this one)

amyleadem · 2023-07-10T16:10:01Z

pages/documentation/settings.md

+```scss
+@use "uswds-core" with (
+  $theme-namespace: (
+    grid: (
+      namespace: "custom-grid-name-",
+    )
+  )
+);
+```


Note
Added a code sample here because it didn't feel immediately clear that grid.namespace lives inside of $theme-namespace based on the info in the settings tables. I thought that adding a code example would show the multiple levels of nesting in these types of settings.

This is so very clear, and I could understand it easily as someone new to this process. Lovely!

amyleadem · 2023-07-10T16:17:42Z

@mejiaj
cc: @bonnieAcameron @mahoneycm
Thanks for the helpful notes. I made a few edits based on your comment:

Reorganized content a bit to improve flow
1. Moved the dot notation section to live directly above the settings tables
2. Moved the compilation error message site note up into the "What to include in your configuration" section
3. Nested "Configuring settings maps" inside "What to include in your configuration"
Changed the code example in the dot notation section to use a selection from the settings tables
Removed site note styling from the dot notation section so that I could add a larger code snippet

Curious to hear what you all think!

mejiaj

Looks great, thanks for updating this!

_data/changelogs/docs-settings.yml

mahoneycm

Very understandable! This will be helpful for newcomers to the system to understand how to update their settings.

Thanks Amy!

bonnieAcameron · 2023-07-21T14:17:00Z

pages/documentation/settings.md

+```scss
+@use "uswds-core" with (
+  $theme-namespace: (
+    grid: (
+      namespace: "custom-grid-name-",
+    )
+  )
+);
+```


This is so very clear, and I could understand it easily as someone new to this process. Lovely!

_data/changelogs/docs-settings.yml

Add note about settings with dot notation

c056efe

amyleadem commented Jun 6, 2023

View reviewed changes

Add changelog for #2122

7365e5a

amyleadem marked this pull request as ready for review June 6, 2023 17:02

amyleadem requested review from bonnieAcameron, mahoneycm, mejiaj and sarah-sch June 6, 2023 17:06

mahoneycm approved these changes Jun 6, 2023

View reviewed changes

bonnieAcameron reviewed Jun 6, 2023

View reviewed changes

bonnieAcameron suggested changes Jun 6, 2023

View reviewed changes

amyleadem linked an issue Jun 8, 2023 that may be closed by this pull request

USWDS-Site - Compile: Clarify dot notation for nested settings #2116

Closed

2 tasks

Base automatically changed from release-3.5.0 to main June 9, 2023 23:09

Amy Leadem added 4 commits June 15, 2023 07:08

Merge branch 'main' of https://github.com/uswds/uswds-site into al-do…

437ccb2

…t-notation

Add clarification to dot notation copy

a6cf618

- Add link with more info about dot notation

cfdaaf4

- Make small tweaks to dot notation copy

Add header for dot notation section

789c472

- Make this a section easier to find via screen readers, etc

amyleadem requested a review from bonnieAcameron June 15, 2023 17:54

bonnieAcameron approved these changes Jun 15, 2023

View reviewed changes

amyleadem requested a review from thisisdano June 15, 2023 19:54

Merge branch 'main' of https://github.com/uswds/uswds-site into al-do…

5f24dd4

…t-notation

mejiaj suggested changes Jul 7, 2023

View reviewed changes

Amy Leadem added 4 commits July 7, 2023 12:44

Merge branch 'main' of https://github.com/uswds/uswds-site into al-do…

e56645d

…t-notation

Remove 'or describe' copy from dot notation

13072e8

Copy tweaks to add clarity

0c3c672

amyleadem commented Jul 10, 2023

View reviewed changes

amyleadem requested a review from mejiaj July 10, 2023 16:17

amyleadem requested review from bonnieAcameron and mahoneycm July 10, 2023 16:17

Merge branch 'main' of github.com:uswds/uswds-site into al-dot-notation

75198fd

mejiaj approved these changes Jul 11, 2023

View reviewed changes

mejiaj reviewed Jul 11, 2023

View reviewed changes

_data/changelogs/docs-settings.yml Outdated Show resolved Hide resolved

mahoneycm approved these changes Jul 11, 2023

View reviewed changes

bonnieAcameron approved these changes Jul 21, 2023

View reviewed changes

thisisdano reviewed Jul 28, 2023

View reviewed changes

_data/changelogs/docs-settings.yml Outdated Show resolved Hide resolved

_data/changelogs/docs-settings.yml Outdated Show resolved Hide resolved

Update changelog date

96bf0a1

thisisdano approved these changes Jul 28, 2023

View reviewed changes

thisisdano merged commit 995b9cc into main Jul 28, 2023

thisisdano deleted the al-dot-notation branch July 28, 2023 17:07

	Note: We use dot notation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.
	Note: We use [dot notation](https://builtin.com/data-science/dot-notation) in most of our documentation to describe settings that are nested inside a Sass map. For example, for the code sample above, `$background-color-settings.responsive` would refer to the `responsive` property inside `$background-color-settings`.

		{: .site-note }
		Note: If you receive the error `This module was already loaded, so it can't be configured using "with"`, confirm that all your declared variables exist in the [settings tables](#general-settings) and try compiling again.

USWDS-Site: Add note about settings with dot notation #2122

USWDS-Site: Add note about settings with dot notation #2122

Uh oh!

Conversation

amyleadem commented Jun 6, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Related issue

Preview link

Problem statement

Solution

Testing and review

Uh oh!

Choose a reason for hiding this comment

Uh oh!

mahoneycm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amyleadem Jun 6, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amyleadem Jun 15, 2023 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

bonnieAcameron left a comment

Choose a reason for hiding this comment

Uh oh!

amyleadem commented Jun 15, 2023

Uh oh!

bonnieAcameron left a comment

Choose a reason for hiding this comment

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

amyleadem commented Jul 10, 2023

Uh oh!

mejiaj left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

mahoneycm left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

6 participants

amyleadem commented Jun 6, 2023 •

edited

Loading

amyleadem Jun 6, 2023 •

edited

Loading

amyleadem Jun 15, 2023 •

edited

Loading