Doc Structure Improvements

[davestewart]

Describe the bug

Go to any sub-page on https://wxt.dev and it's a 404.

EDIT 1: only seems to happen if navigating from the Get Started or Learn More buttons on the home page. The top nav menus seem to be OK.

EDIT 2: But, also happened from Google search results:

• https://www.google.com/search?q=wxt+messaging

It seems maybe the getting-started and guide links are pointing at the wrong folders?

Get Started:

• https://wxt.dev/guide/installation.html (link, broken)
• https://wxt.dev/get-started/introduction.html (page)

EDIT 3: looks like #701 broke this, so fix needed + 301 redirects.

FWIW, I absolutely HATE the Nuxt "Key Concepts / Directory Structure / Going Further" approach; I feel it's "cart before the horse"; rather than thinking in terms of "what do I know about how extensions work" it starts with "these are the units of our framework" and the end result is a really fragmented reading experience from which you have to jump across multiple docs just to understand any single development arc.

IMHO:

• Having separate "Get Started" and "Guide" results in fragmented and duplicated content
• The "Directory Structure" approach has always felt like the most counter-intuitive way to introduce information
• "Going Further" for most developers is the opposite; half of these things you would want to know at the start

I know VuePress pretty well (my site is built in it) and would be really happy to explore an alternative structure (I've lots of writing and docs experience). I actually think the previous docs were pretty solid, but understand that you want to organise the main guide page (which I'm now running locally).

FWIW I think the VitePress, Astro and Next docs are all excellent; straightforward and logical

Reproduction

https://wxt.dev/guide/installation.html

[aklinker1]

Fixed links and added redirects in the short term. Should be working now. Just forgot to update the homepage lol.

[davestewart]

Any thoughts on my thoughts?

Totally up for collaborating on docs, esp if it gives you more time on the code 😊

[aklinker1]

Sorry, woke up to several comments from people telling me the docs were broken lol, so my goal was to get that resolved first. Haven't had time to go through your comment in detail, will do it today after work!

Thanks for the in-depth comment though, and I appreciate your offer to help restructure it. I've been swamped with tickets and help requests on discord, and I haven't had time to actually work on the framework for a while. So any kind of help would be appreciated.

I needed to shake things up and try something else for the docs website. That's why I just did it out of the blue yesterday.

[davestewart]

That sounds promising! OK, no hurry, have a great day

[aklinker1]

FWIW, I absolutely HATE the Nuxt "Key Concepts / Directory Structure / Going Further" approach; I feel it's "cart before the horse"; rather than thinking in terms of "what do I know about how extensions work" it starts with "these are the units of our framework" and the end result is a really fragmented reading experience from which you have to jump across multiple docs just to understand any single development arc.

IMHO:

• Having separate "Get Started" and "Guide" results in fragmented and duplicated content
• The "Directory Structure" approach has always felt like the most counter-intuitive way to introduce information
• "Going Further" for most developers is the opposite; half of these things you would want to know at the start

I like the separate "Get Started" and "guide" sections, because no developer will be able to read through all the docs at once. There's too much. Instead, just read the smaller "Get Started" pages from start to finish so you have an understanding of the framework, then look at the guide for more details. I think duplicate content is just a side effect of this approach. I would prefer to avoid this if possible, but need help finding a better structure.

rather than thinking in terms of "what do I know about how extensions work" it starts with "these are the units of our framework"

I can't explain all of extension development in my docs, you have to assume a certain knowledge level, and my assumption is that you know how chrome extensions function. Not really sure how to improve this, but I have been getting too many basic questions below that knowledge level assumption, so any ideas you have around this would be great.

I know VuePress pretty well (my site is built in it) and would be really happy to explore an alternative structure (I've lots of writing and docs experience). I actually think the previous docs were pretty solid, but understand that you want to organise the main guide page (which I'm now running locally).

FWIW I think the VitePress, Astro and Next docs are all excellent; straightforward and logical

I actually HATE the vitepress docs, I can never find what I need, at least around customizing the default theme. The rest of their docs are pretty solid, but I never know if the default theme info is in the guide or the API reference. Usually in the API reference, but none of that code mentions any API.

Both Nuxt and Astro have a single section basically, where all the concepts are listed in the sidebar. Don't mind this, but isn't it too much for a first time reader? There's no way I can get through all that stuff. I'm gonna end up picking and choosing different pages as needed instead of getting a comprehensive overview of what I need to know.

[leetrout]

Dave said:

Having separate "Get Started" and "Guide" results in fragmented and duplicated content

Aaron replied:

I like the separate "Get Started" and "guide" sections, because no developer will be able to read through all the docs at once.

So I'll toss this out: you both might enjoy this breakdown of documentation if you've not seen it before. In support of this issue but far beyond the scope of "just" this issue... it's a good read IMO. I always encourage folks to start on the right side of the axis and trend to the bottom. Universally, I think everyone needs reference and then when you work backwards from that how-to guides are the easiest to knock out.

https://diataxis.fr/

[davestewart]

Hey @aklinker1,

Thanks for your notes!

I think we're actually aligned on the key points:

• assume previous extension development knowledge
• must be straightforward to get up and running quickly
• VitePress docs solid apart from customising default theme (I ended up ejecting mine; soooo much easier!)
• unified docs á la Astro could work, if clearly structured to cater for first-time use

And I should like to say also, credit to your hard work; you've documented a lot and it is very nicely-written 🙏

Having gone through your new docs again I'm pretty sure I could build on what exists – so how about I just fork and iterate on a new structure?

I'm pretty sure I can find a route through that will work for both window-shoppers and those planning to make a more long-term investment in the framework, whilst addressing the key issues of discovery, fragmentation and duplication.

I could get a first pass up and running in the next couple of days, then we go from there, if that works? And if you don't like it, no big loss; at least it means one more person will have read all the docs!

[aklinker1]

And I should like to say also, credit to your hard work; you've documented a lot and it is very nicely-written 🙏

Thank you! Other than the typos 🙈 I've been using Zed lately, and it doesn't have a spell check extension yet... Or it didn't a month ago last time I checked.

VitePress docs solid apart from customising default theme (I ended up ejecting mine; soooo much easier!)

I've never done this, but I don't really want the overhead of maintaining what I imagine an injected setup would look like, so let's keep it vanilla for now.

so how about I just fork and iterate on a new structure?

@davestewart yup, I think we're aligned, and I think that's a great idea! LMK if you have any questions as you go through them more.

Only thing to point out is the doc/.old directory storing a file I didn't fully migrate to the new structure yet.

[aklinker1]

@leetrout Thanks for sharing! I've started reading through it, but it's like a small book lol. Haven't gotten to any actionable steps, just reading about the 4 different types of documentation. Hopefully we can apply some of those learnings on the upcoming improvements.

[aklinker1]

Hey @davestewart, I think I'm gonna start updating the structure a bit, and if you have time, I'd like your feedback!

And yes, this time I will be adding redirects so no old links break

Here's my plan:

1. Get rid of separate "get-started" sidebar, and merge it into the guide
2. Break the guide apart into different sections

I really like how astro just lays everything out - I'm going for something similar

Here's a rough outline of what the sections will be:

• Get Started
  • Introduction
  • Installation
  • Migrate to WXT
• Core Concepts
  • Project Structure
  • Entrypoints
  • Browser Support
  • Vite
• Configuration
  • Main Config File
  • Manifest
  • Browser Startup
  • Environment variables
  • Runtime Config
  • Frontend Frameworks
  • TypeScript
• Extension APIs
  • Storage
  • Messaging
  • Scripting
  • I18n
  • Types
  • Other
• Assets
  • Images
  • CSS
  • WASM
• Content Scripts
  • Overview
  • Content Script Context
  • UI
• WXT Modules
  • Overview
  • Recipes
• Maintain Your Project
  • Upgrading WXT
  • Unit Testing
  • E2E Testing
  • Debugging
• Going to Production
  • Publishing
  • Bundle Remote Code
  • Testing Updates
• Entrypoint Types
  • <all the different entrypoint docs>
• Resources
  • Examples
  • Compare
  • How WXT Works

I think that should cover everything for wxt.

I am beginning to release first-party packages you can use with WXT, like @wxt-dev/i18n that also need a place on the website. I'm considering adding a drop-down to the top navigation to select the package you're looking at, but am not convinced that's the way to go :/ If you have any ideas, I'd love to hear them!

[davestewart]

Hey @aklinker1,

Sorry for the late reply and lack of input, work (and, actually some fun OSS, finally!) has been rather all-consuming over the last couple of months!

I think this sounds really good.

I might suggest the following though:

Configuration

• Main Config File
• Manifest
• Browser Startup
• Environment variables
• Runtime Config
• Frontend Frameworks
• TypeScript

Assets

• Images
• CSS
• WASM

Application Logic

• Overview
• Entrypoints
• Content Script Context
• UI

Extension APIs

• Storage
• Messaging
• Scripting
• I18n
• Types
• Other

WXT Modules

• Overview
• Recipes

In summary:

• moved "Assets" after "Config" as effectively it's really just configuration
• moved "Extension APIs" to be between "Content Scripts" and "WXT Modules" as they all feel like code
• renamed "Content Scripts" to be "Application Logic" (tried a few names, but essentially this is the bones of the app, and would include the service worker, etc)
• added "Entrypoints" (a more detailed version) here rather than having to jump to "Core Concepts" each time

Really, I'm just thinking though probably the development process I would go through when piecing together the parts of an extension I might build, i.e. the floor before the walls, etc. and where I would be in the docs.

My two main main beefs with the Nuxt docs were:

• duplication of similar but subtly-different content across multiple sections (which it sounds like you are solving here)
• the directories section, which is a really unhelpful inversion of folk's existing knowledge (say if you know routing, you have to eventually stumble on "/pages" rather than going "ok, how do I do routing?")

I think the "Entrypoints" section could easily be explained on a single page with a "concept" explainer, and either subsections, a table or two, or links to the API, for the various flavours.

FWIW I think a Quick Start section could still work:

• it could just be a single page, and more of a jumping-off point, rather than full guide
• a way in for the developer looking to spend 5 minutes opening a GitHub repo and referencing a couple of docs pages
• filter users based on intent, such as:
  • new to extension development
    • discuss high-level concepts
    • point to Chrome docs
    • wxt hello world (only!) repo
  • experienced extension developer
    • quickly explain key architecture differences
    • point to main docs sections
    • intermediate repo
  • window-shopper
    • explain the most interesting features
    • show a variety of example repos / point to Examples
• for each:
  • don't repeat code
  • have the user install the examples
  • let well-commented code do the heavy lifting

I get there could be a crossover with the Examples section; perhaps the Examples is effectively the "Further reading" for this section.

[aklinker1]

@davestewart Thanks for the feedback! I worked on it the last few days, and a partial version of the new docs is live, with a few changes from what I originally posted.

https://deploy-preview-933--creative-fairy-df92c4.netlify.app/

I think it aligns with some of the changes you suggested