search

wxt-dev / wxt

⚡ Next-gen Web Extension Framework
https://wxt.dev
MIT License
3.24k stars 118 forks source link

Doc Structure Improvements #704

Open davestewart opened 4 weeks ago

davestewart commented 4 weeks ago

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:

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

Get Started:

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 commented 4 weeks ago

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

davestewart commented 4 weeks ago

Any thoughts on my thoughts?

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

aklinker1 commented 4 weeks ago

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 commented 4 weeks ago

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

aklinker1 commented 3 weeks ago

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 commented 3 weeks ago

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 commented 3 weeks ago

Hey @aklinker1,

Thanks for your notes!

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

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 commented 3 weeks ago

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 commented 3 weeks ago

@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.