[Epic] Populate manual content

[PtitBen]

Outcome

Each component has all the manual content required for a full doc

Scope

Sections to be completed for all components.

Overview

• Purpose (PR: Create temp-draft-purpose.md #273 )
• [Docs content] HTML Examples #284
• Add HTML examples to relative directories in Docs #315
• [Docs content] Related links and footer section #314

Guidance

• Types (text based content - for HTML examples see above links)
• Content Guidance See [Docs content] guidance images #263
• Examples (snippet + preview) - see [Docs content] HTML Examples #284

Implementation

• Specs notes (+ tables) See Spec list #326 and Specs user testing #328
• Do & Don't (using Aside feature) #294
• Best Practices (text content)
• Accessibility

(This approach has changed from completing each component individually. Following the discussion on 6 December it was agreed we can proceed with creating 1 file of content with all components covered for each section to allow work on the technical aspect to proceed in parallel until ready to unite).

[RobTobias123]

The 'Purpose' section PR was created and an initial temp file was added. Content is now being added.
#273

Each purpose section has 2 parts - a one liner highlighted at the top of the doc and an explanatory paragraph that can expand on this in a little more detail.

Each purpose is being copied to the .md file and committed before being rephrased to improve the grammar correctness and clarity etc. and commited again to the PR above. This way we can review original vs proposed.

Goals used for rephrasing: Audience - knowledgeable, Formality - neutral, Domain - general, Intent - inform.

[RobTobias123]

All purposes have been added to the initial temp file and rephrased accordingly, attempting to retain consistency in format across each.

PR for review please: #273

[RobTobias123]

Following review and feedback this morning:

• Component names in purposes follow the same simpler, clearer convention of 'Use ns-xyz to...' instead of 'Use the XYZ component to...'
• All component names in purpose are displayed using back-ticks
• An example of the automated deprecation message as a Starlight 'caution aside' also contains an example of the back-ticked display of the component name with link. (Is this too specific?)
• Image references removed (image/examples will be part of the overview, not purpose section)
• Parsed corrected to passed
• Checked the contrast ratio of the back-tick text-background and text and it appears it needs changing in the custom.css as not quite enough contrast (light mode) for the size (needs to be 4.5:1):

[RobTobias123]

Following our team's conversation this morning it was decided that it was not necessary to repeat the component names in the 'purpose' one-liners (which will be assumed to reside in the component js and be pulled into the docs to automate).

PR for review please: #273

[RobTobias123]

Updated purpose text to not refer to 'We use...' to retain correct focus.
Reworded ns-alert secondary paragraph to be more generic and consistent with others.
Adjusted and checked custom.css colour values for light and dark to ensure 'Deprecated' pill and back-ticked names meet contrast ratio requirements.

[RobTobias123]

I've started adding the index pages and adding the updated purposes as discussed earlier today with Mekala, I've just worked on ns-a... so far and amended what was already there or added new ones based on the example set of pages Drew created.

Note that on ns-article, I have included that standard deprecation message we mentioned. I've added it to the top of all of that component's pages as it would need to be clear on all pages if the user hadn't arrived via the Overview page etc. I think I'll flesh out this "ns-a..." category with all the content in the right places for now before rinse and repeat for the others.

I have also noticed we have Purpose/Types on the Overview page, we also have Types under Guidance on the default structure ticket #245 but I will assess as I go in case that feels like duplication...

[RobTobias123]

Added ns-tabs overview and example and amalgamated ns-tab into it. Branch feature/tab-into-tabs - this will negate the need for a separate ns-tab page as that component is never used in isolation.

We will be looking to do similar with ns-timeline and ns-timeline-event.

[RobTobias123]

Creating component HTML files for docs snippets "_examples" based on Storybook. Agreed approach is to name each file as its type. The default is standard.html, others may have appendages conjoined with underscores, eg. direct_link.html and direct_button.html.

Accordion to CTA done so far and saved locally for inclusion once Drew has completed work on his branch affecting the file structure.

Point to note: The ns-cta has many types and an example of each that shows loading, or within form etc. My thoughts were that perhaps that could be a configuration option? Eg. a checkbox for 'Loading state' etc? (similar to how we used 'knobs' or 'controls' in storybook?)

[RobTobias123]

All HTML _examples for general components (accordion to video) have been created and saved locally (as above). Form components _examples now in progress.

[RobTobias123]

All HTML _examples for form components (appointment-picker to selector) have been created and saved locally (as above).
I have marked a couple as I have some questions that I will compile for addressing in the next docs catch up (tomorrow).

deprecated and nsx experiences _examples now in progress.

[RobTobias123]

HTML _examples for deprecated and nsx experiences have been created and saved locally.

[RobTobias123]

Observation:

Some snippet examples use British Gas type content, others in Lorem Ipsum. The components are visually British Gas style and these particular set of docs I understand are for British Gas. So I am anticipating a similar but nuanced set for any other brand that may adopt Nucleus, rather than a one-size-fits-all, vanilla Nucleus set of docs.

Question:

It could be better if we make it all consistent, but which way? Having content relevant to the business using it might illustrate the example usage well, but is it taken too literally, and just copied without changes being considered? Using a random irrelevant topic for content has also been shown to confuse. And using Lorem Ipsum may seem too vague.

What is the consensus on this?