Documentation Updates

[endigo9740]

As we prep for v1, I'd like to do one more sweeping pass through the documentation to polish it off. This will be a segmented pass that is made up of multiple tickets, including but not limited to the following:

Required

• Doc Site SEO + Open Graph #355
• Replace Google Analytics #736
• Reorganize the /docs directory #978
• Refactor onboarding, guides, and doc sections #981
• Doc Shell overhaul #977
• Feature Preview Component #1031
• Audit and Improve Doc Content #1049
• Documentation homepage redesign #1070
• Responsive design audit #1058

Nice to Have

• Redesigned Search modal (reference)

NOTE: I've dropped the blog section updates for now, let's circle back on those later.

[cailenxyvid]

Re: item 9 - I'm happy to help with proof reading / editing tasks, when that time comes.

[Hugos68]

Re: item 9 - Would gladly work on this when needed.

[Hugos68]

Menu docs: Menu page title (singular) doesnt match up with navbar on the left hand side (plural)

[endigo9740]

Idea: on the blog, provide a set of pinned blog posts at the top for useful guides. Implement category tag filtering.

[endigo9740]

This is something we should take into consideration for our documentation updates.
https://discord.com/channels/1003691521280856084/1070425953798467664/1070425953798467664

Providing more guidelines for use cases for each component like Google does with Material Design (ex: limit 3-7 items for the app rail)

[szachy113]

I am eager to assist with anything you may need. Just let me know how I can be of service.

[endigo9740]

Reminder: document @AdrianGonz97 PurgeCSS plugin (when ready) for use with Skeleton:

• Implement Purge CSS #732

[endigo9740]

Idea: Use Faker.js to generate fake data for examples, tables, avatars, etc
https://fakerjs.dev/

[endigo9740]

FYI I've updated the original post above to better reflect the upcoming process for these changes.

@cailenxyvid @Hugos68 @szachy113
let me know if you're still good to help with auditing and improving the copy for the doc site. We're not quite at that step yet, but it's coming up soon. Probably starting next week.

[cailenfisher]

FYI I've updated the original post above to better reflect the upcoming process for these changes.

@cailenxyvid @Hugos68 @szachy113 let me know if you're still good to help with auditing and improving the copy for the doc site. We're not quite at that step yet, but it's coming up soon. Probably starting next week.

Sounds good to me, I'm down. This is my personal account, I probably can't justify helping out here while on the clock :)

[endigo9740]

Cool, general idea is I'll need all three of you on Discord and I'll setup a dedicated channel for us to coordinate on this. I have a loose plan for how I want to tackle this, but I'll formalize this before then. And of course, timezones and other considerations will be taken into account. I don't expect this to be solved in a single day.

[endigo9740]

Update contribution guidelines, including linting, prettier, and other VS Code editor configs, such as the settings.json script cBase style autosuggestion tweak:

{
    "tailwindCSS.experimental.classRegex": [["/\\*tw\\*/ ([^;]*);", "'([^']*)'"]],
}

[niktek]

Need to adjust lint rules to ignore backlash quotes in @html blocks

[ghost]

@endigo9740, I was doing a sweep of the guides, and, so far, I found a grammatical error in the installation guide. Do you want me to open a PR now, do you want me to wait until I find more errors in the docs, or do you want me to wait until most of the subtickets are completed? I don't want to cause any merge conflicts, which is why I'm asking. If you want me to go ahead and open a PR, I'll need to know which commit to branch off of to avoid interfering with other PRs. I'll also need to know what directory the guides are in; I tried looking in the src/docs folder, but I think the guides are very deep in the docs directory.

[endigo9740]

@IRod22 were these issues on the dev or master branches? We're about to drop a whole slew of updates to those sections in tomorrow's release. Preview here:

https://dev.skeleton.dev/docs/introduction

I'd say hold off until we put out a call to arms. I have two other updates I want to get in place before other folks start touching the doc pages, otherwise we might end up duplicating effort.

1. The doc shell update - this may potentially drastically alterer the page layout for more "inner" pages
2. The new "Previewer" component - which will allow users to quickly toggle between preview/code

I have a basic proof of concept of number two on the Code Blocks page here.

FYI most documentation pages exist in the Routes directory of the project, so /src/routes/(inner). The /docs directory is a place for us to house doc-specific components and features.

[ghost]

@endigo9740, thank you for letting me know. I'll hold off on the docs for now and, when Skeleton is in the RC stage, put Skeleton through its paces instead. Feel free to @mention me when y'all are ready, and I'll take a look. RC Tester @IRod22 will report for duty after tomorrow.

[endigo9740]

@cailenxyvid @Hugos68 @szachy113 @IRod22 FYI I've created a new #docs-overhaul channel on Discord. I highly encourage you guys join and read my notes there. This details the status and plan for handling the upcoming doc audit and review from volunteers like yourself. Keep an eye on that channel this week and I'll let you know when we're ready go.

Also please post a quick "hey I'm X person on GitHub" so I can keep everyone straight please heh. Thanks!

[ghost]

@endigo9740, I'm sorry to say this, but I'm not on Discord; I'm trying to limit my social media footprint right now, and I'm a bit concerned about Discord's safety and security practices...

[endigo9740]

Sorry, unfortunately that's our primary place for real-time collaboration. There's zero chance I'm going to be able to replicate all information from there to here. There's just too much to try and echo it all. I might suggest creating a throwaway account to get you by for now, otherwise we appreciate we appreciate the offer. There's always a chance something slips through and we would welcome addition eyes in the future though.

[ghost]

No, I'm sorry. I'll just be an RC tester.

[endigo9740]

• Error on the Toast docs - present has been replaced with background

[endigo9740]

• It looks like we have several broken links in our page footer - those will need to be addressed

[Hugos68]

FYI I've updated the original post above to better reflect the upcoming process for these changes.

@cailenxyvid @Hugos68 @szachy113 let me know if you're still good to help with auditing and improving the copy for the doc site. We're not quite at that step yet, but it's coming up soon. Probably starting next week.

Missed this, Yeah I'm still down to help with cleaning up the docs 👍

[endigo9740]

Awesome, the ETA to begin is probably Monday or so next week (US time)

[endigo9740]

• Typo on quickstart: Typo in Quick Start #1037

[endigo9740]

• Light Switch; let's make it more clear that three options are presented on the page and they should not be used in parallel:

1. Lightswitch - plug and play, drop it in and you're done
2. OS Preference - requires a quick import and one step
3. Create your own Lightswtich - requires creating a custom component and importing the utility methods provided

https://www.skeleton.dev/utilities/lightswitches

[endigo9740]

• Popups: let's ensure the setup instruction is clear. There's been some confusion on the order of imports and how to replicate Menu/Tooltip functionality.

[jhiney]

• Not sure if it has been mentioned yet but the link to the contribution guidelines in the readme goes to a 404 page (/docs/contributions) rather than the actual page (/docs/contributing).

[endigo9740]

Great catch @jhiney. I'll add that to my list!

[endigo9740]

The text audit and homepage redesign issues have now been marked Closed.