Standardize documentation structure across all packages #13
ViewFromTheBox
started this conversation in
Organization-wide Tasks
Replies: 0 comments
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Uh oh!
There was an error while loading. Please reload this page.
Why
Each package keeps its documentation in its own
docs/folder, and docs.artisanpackui.dev builds from those folders. The packages have drifted apart over time. Each difference is small, but together they mean the site doesn't have one predictable structure. The same kind of page has a different name in different packages, sections show up in different orders, and some packages are missing pages that others have.This discussion tracks the work to bring every package's docs onto one shared structure.
What's inconsistent today
A survey of every repo's
docs/folder found these problems:getting-started.md).cms-frameworkandvisual-editoralso use Title-Case names (Installation-Guide.md,Quick-Start.md,Developer-Guide.md), sometimes alongside kebab-case pages that cover the same topic.api.md,api-reference.md,reference.mdorpsi-api-reference.md, depending on the package. The entry page isgetting-started.md,Quick-Start.mdoroverview.md.home → getting-started → installation → usage → advanced → api → faq → troubleshooting. A few use a shorterhome → guide → referencelayout (ai,bing-places,google-business-profile,icons). Others use a flat list of topic pages (hooks,hooks-js,pagespeed-insights,ecommerce).docs/folders contain planning notes, audits, decision records or changelogs that aren't meant for users. Examples:core/install-packages-command-plan.md,seo/og-image-backend-decision.md,ecommerce/audits,ecommerce-admin-livewire/plansandhooks/changelog.md.upgrading.md,upgrade.md,migration.mdand per-versionupgrade-x.y.z.mdfiles.google-ads,google-data-studio,liquid-glass,security-fullandshipping-labelsdon't have adocs/folder yet.The plan
.githubrepo orpackage-blueprintso it's easy to find.docs/, into a folder such as.planning/or the repo root, so only user-facing pages are published.docs/folder to match the blueprint, then fill in any missing required pages.artisanpack-ui-docsand check that the site's navigation is consistent across every package.Comment below with feedback on the standard or with packages that need special handling.
Status
🔵 To do · 🟡 In progress · 🟠 In review · 🟢 Done · 🔴 Blocked
The table below will be updated as each package moves along.
accessibilityaiguide/referencelayoutanalyticsanalytics-googleapple-oauthbing-placesguide/referencelayoutbookingscms-frameworkcode-stylecode-style-pintcomplianceconvertkitcoredocs/design-systemecommercedocs/ecommerce-admin-livewiredocs/ecommerce-kanban-livewireecommerce-paypalecommerce-storefront-livewireformsgooglegoogle-adsdocs/foldergoogle-business-profileguide/referencelayoutgoogle-data-studiodocs/foldergoogle-search-consolegoogle-tag-managerhooksdocs/hooks-jsiconsguide/referencelayoutliquid-glassdocs/folderlivewire-drag-and-droplivewire-starter-kitlivewire-ui-componentsmedia-librarymicrosoft-oauthpagespeed-insightsperformanceprivacyrbacreactreact-starter-kitsecure-uploadssecuritysecurity-advanced-authsecurity-analyticssecurity-authsecurity-fulldocs/folder (meta-package)seodocs/shipping-labelsdocs/folderspecificationdocs/visual-editorvuevue-starter-kitAll reactions