Docs: open issues & questions

[kmcfaul]

Capturing some questions and things to decide on regarding documentation to improve consistency.

General documentation:

• KeyboardHandler and Popper are exported and should be included in our docs, but are not currently. consider documenting the utilities under the website "Utility". We could have React and CSS sub categories.

• CSS variables section could be moved out of each page and into a separate tab to cut down on page length (and demo pages are not consistent on whether this section is included)

• Would it be worth introducing another sub-level into the sidebar navigation to group similar components together (ex. grouping Textarea, Text input, Text input group into a new folder Text under Components) or would that be too many levels of drill-in?

• Should Legacy use a badge/banner similar to Beta to further visually distinguish components/examples instead of using text? This would also cut down on example title length. Open org issue and design issue for the deprecated badge. open design issue for deprecated banner.

Example-related:

• Data sets in component examples sometimes use practical, real world-like data (Dell, Samsung...) vs. descriptive data (Option 1, Option 2...), sometimes swap data set types between examples on the same component page, and sometimes analogous examples between react+html do not match data set types. We might want to pick one type of data, or form data sets relevant to each component and be consistent within a component page for react and html. components should be reviewed for content in examples/demos before it is promoted from Beta. Open issue to update example/demos for real world vs descriptive data.

• Examples with common features repeat phrases in their titles and could be grouped under a subheader instead (ex. AlertGroup has “Singular dynamic alert group”, “Singular dynamic alert group with overflow message”, and “Multiple dynamic alert group” examples)

• Examples use flag modifier elements inconsistently - sometimes included above vs. below the example, sometimes uses checkbox vs. button vs. radio. Tooltip has a large table of options modifying a single example.

• Example titles between react and core are inconsistent for analogous examples. There is also inconsistency in the term used for basic use case examples (between "basic", "default", and "simple").

• Should example titles use punctuation? Most example titles do not which make the several that do stand out

[kmcfaul]

@tlabaj @mcarrano

[mcarrano]

@kmcfaul thanks for compiling this list. It's great feedback! We'll just need to figure out how to address these issues.

cc @wolfeallison @edonehoo

[mcarrano]

@wolfeallison @edonehoo Can you take a look through this and let us know what changes make sense and we'll try to start to get these in the queue.

[edonehoo]

@mcarrano talked to @wolfeallison and neither of us has complaints about these ideas. They all generally make sense and would be nice changes. There are a few points where we are missing additional context (re: keyboardhandler/popper, data sets data). Additionally, a handful of these seem like a best-practice decision needs to be made, and then everything should be updated to match for consistency, but I'm not sure who all should be part of the conversation to decide what the standard should be (re terminology for "basic" examples, flag modifier elements).

and a couple of thoughts on specific questions:

• Should example titles use punctuation? - No they shouldn't
• Would it be worth introducing another sub-level into the sidebar navigation to group similar components together? - This seems fine, especially since a third level of navigation is already planned for the IA project

[mcarrano]

Additionally, a handful of these seem like a best-practice decision needs to be made, and then everything should be updated to match for consistency, but I'm not sure who all should be part of the conversation to decide what the standard should be (re terminology for "basic" examples, flag modifier elements).

Good question @edonehoo . I'm willing to accept a consensus opinion between content and development. If that's hard to get to, we can do something more scientific to test certain words. But that ultimately makes reaching a decision more complex. My two cents is that "default" has a very specific meaning so we should be careful to use that term unless there truly is a default option.

[edonehoo]

I would agree that "default" sounds more specific and suggestive. I lean towards "basic" personally, but there's nothing necessarily scientific behind that.