Audit and Improve Doc Content

[endigo9740]

Per: #783

The goal of this ticket will be to divvy up ownership of several sections of the documentation. Each volunteer will be assigned an allotment of pages that they will own. You should audit, review, and either submit feedback - or better yet send a PR with fixes and adjustments in place.

How to Participate

Warning please DO NOT volunteer if you cannot have your changes completed by Sunday March 5th.

1. Reach out in the #docs-overhaul channel on Discord to volunteer
   • Post your GitHub username (I'll assign you below)
   • Let us know which section you wish to be assigned
2. Immediately create a draft PR (pull request), including your checklist as shown below (reference)
   • Important: You will not be considered assigned until a draft PR is available
3. As you complete changes per page, commit it, then tick the box in the PR to alert everyone of your progress
4. Set your PR to "ready for review" when all sections are complete
5. Finalize all changes by Sunday March 5!

Can't submit a PR?

View the dev branch docs here:
https://dev.skeleton.dev/docs/introduction

You can still help by locating issues for other volunteers, reviewing the blog posts, or helping with PR reviews. When submitting feedback, tag the assigned user, or consider keeping feedback feedback localized in each PR thread. Use a checklist so we can tick off items as completed!

Responsibilities

Try to follow any obvious existing conventions. Contact a contributor on Discord for additional questions!

• Scan the page for typos, grammar, etc (including each tab)
• Check the page for broken links
• Keep headings short, consistent, and semantic to the section (no wrapping in Table of Contents)
• Keep paragraph text short, concise, and descriptive - ideally 1-2 lines max
• Use h2 for main headers, h3 for subheaders
• Use <section class="space-y-4">...</section> to divide page sections
• prop, slots and event tab data is auto-documented via inline JSDocs comments (reference)
• Ensure auto-documented tables aren't missing props (it happens!) and descriptions are semantic
• The classes, params, and keyboard tabs are manually maintained, which means more room for error
• Avoid inserting Font Awesome icons in code snippets - Skeleton is icon library agnostic!
• On CodeBlock snippets remove trailing indents so that they are not copied over to the clipboard

See the Doc Updates comments for suggestions made by other users.

Standby Volunteers

Folks that aren't committing to any section, but are available to help scan for issues or check other's work:

• @riziles
• @SebasF1349
• @dirk-bester
• (Hugos)

Source

• /src/lib/{category}/{feature} - the library features themselves (components, element styles, etc)
• /src/routes/{category}/{feature} - the documentation pages for each respective feature

Progress

Blog (open/anyone)

Note - review each blog post. Scan for out of data info, typos, etc. Report issues in the comments below.

Tailwind - Group 1 (oatnog)

PR: (not yet available)

• Core
• Typography
• Forms
• Alerts
• Badges

Tailwind - Group 2 (DukeRupert)

PR: (not yet available)

• Breadcrumbs
• Buttons
• Cards
• Chips
• Lists
• Logo Clouds
• Placeholders
• Tables
• Gradient Headings

Svelte - Group 1 (niktek)

PR: 1054

• Clipboard
• Filters
• Focus Trap
• Accordions
• App Bar
• App Rail
• App Shell
• Avatars
• Conic Gradients
• File Buttons
• File Dropzone
• Input Chips

Svelte - Group 2 (RyanTheGuy)

PR: #1055 (ready for review!)

• Listboxes
• Paginators
• Progress Bars
• Progress Radials
• Radio Groups
• Range Sliders
• Slide Toggles
• Steppers
• Tabs
• Tables
• Table of Contents

Utilities (DukeRupert)

PR: #1071

• Code Blocks
• Drawers
• Lightswitch
• Local Storage Store
• Modals
• Toasts
• Popups

Docs Sections - Group 1 (@Sarenor)

PR: #1084

• Docs > Introduction
• Docs > Get Started
• Docs > Colors
• Docs > Styling
• Docs > Design Tokens
• Docs > Variants
• Docs > Theme generator
• Docs > Quickstart

Docs Sections - Group 2 (@Sarenor)

PR: #1086

• Docs > Contributing > Requirements
• Docs > Contributing > Style Guide
• Docs > Contributing > Documentation Guide
• Routes > Templates > +page.svelte
• README
• Page footer

Homepage

• See: Documentation homepage redesign #1070

[endigo9740]

• Browser support indicators should be set to use true green/yellow/red rather that using theme colors. Otherwise the visual weighting is messed up:

[endigo9740]

• Doc Shell header has a typo for Element pages:

[RyanTheGuy]

• Accessibility is spelled "Accessability" In several places outside my section, Modals, Drawers, Forms, breadcrumbs, and focus-traps

[endigo9740]

The above "global" issue above have been addressed per #1051

[endigo9740]

• After some back and forth, I think we'll be wise to go ahead and reimplement a small, minimal blurb on the Utility features that rely on stores and bring back the SSR warning (Modals, Toasts, Dialogs).

Here's the original markup for that:

<h2>SvelteKit SSR Warning</h2>
<p>
	Be aware that there are <a
		href="https:/sveltejs/kit/discussions/4339#discussioncomment-2384978"
		target="_blank"
		rel="noreferrer">known issues when using Svelte stores with SSR</a
	>, such as our drawer store. To prevent these issues please avoid the use of the drawer store within any SvelteKit Load function.
	Likewise, if you need a drawer to open on route initilization we advise triggering the <code>open()</code> method after the
	<a href="https://kit.svelte.dev/docs/modules#$app-environment" target="_blank" rel="noreferrer"
		>SvelteKit Browser environment context</a
	> is available.
</p>
<CodeBlock
	language="ts"
	code={`
import { browser } from '$app/environment';\n
if (browser) drawerStore.open(settings);
	`}
/>
<p>
	For additional context please see this <a href="https:/skeletonlabs/skeleton/pull/580" target="_blank" rel="noreferrer"
		>thread</a
	>.
</p>

However, I think what I'd rather do is explain this in a external post - perhaps a Wiki page here on GitHub, and link to that rather than trying to explain this over and over per each of these documentation pages. It's not really our duty to police this, but there's no harm in giving it a shoutout to help educate folks.

[riziles]

• Moving this comment here per @endigo9740 's request.

@niktek , seems to be a minor issue on

https://skeleton-docs-oi8f3pcbb-skeleton-labs.vercel.app/components/app-shell
|-> slots -> header

I believe this is the offending line: https:/niktek/skeleton/blob/f4a0fa09a55f9f69d93f2e56d85bb79c1288a8c0/src/lib/components/AppShell/AppShell.svelte#L3

[Sarenor]

• run a final global find & replace for abitrary -> arbitrary
• Update the roadmap beyond 1.0? @endigo9740 Skeleton Roadmap to v1.0 #503

[endigo9740]

@Sarenor the roadmap extensions post v1 will happen after the v1 launch and require some group meetings and planning. We have a lot of loose ideas, we just need to formalize those. Likewise we need to factor in my time, which will be devoted mainly to Skeleton Lab's project for a bit.

[Sarenor]

@endigo9740 All good, I guessed as much :)
We just link to the roadmap a couple of times and having it say "The road to v1.0" after 1.0 is something to fix, but not immediately.

Could do a temporary replace after the v1 launch: "Chris takes a well deserved rest" until you're back from resting and we had time to plan :)

[riziles]

• issue with Theme Generator page not loading correctly

If I enable preview on the Theme Generator, go to a different page and then come back to the Theme Generator then the page does not load correctly. Chrome dev tools shows the following error:

uncaught (in promise) cannot read properties of null (reading 'ownerDocument')

[endigo9740]

@riziles I've split your issue off to it's own ticket here: #1105

With this I'd recommend that all remaining text changes come in as individual reports or PRs. I'm marking this complete for now.