Replies: 3 comments 11 replies
-
I like this idea. I think this will solve the ordering problem for guides and tutorials. We should make it mandatory for guides (we want the order to be a content decision) and forbidden for all page types that don't use it (or else it won't be maintainable). We can be restrictive at first, and open the system to more page types if the need appears. Like for |
Beta Was this translation helpful? Give feedback.
-
This looks a bit like slapping a Band-Aid on the broken sidebar. The discussion of weighting is perfectly reasonable, but we should not predicate it on things like learn modules or problems with ordering. If the sidebar provided context you could use any ordering approach you liked. Rant over There are three common approaches for sidebar organization
MDN is kind of a hybrid of the first two with a monolithic definition, various dynamic import mechanisms, and quicklinks. All the approaches have their upsides/downsides.
|
Beta Was this translation helpful? Give feedback.
-
So I've been thinking about this - I am 100% on board with finding a good way to order pages. Tutorials/learn and listing api pages specifically. One thing I consider a lot is I can't find a good solution that isn't fragile. Listing sub pages, macros, weighting - they all require knowledge of the pages and the order and with contributions would this get broken easily? However I agree with @wbamberg weighting is one of the simplest approaches and I prefer it to other suggestions, I just worry that I personally assume weight backwards (100 is heavy and important, whereas 0 is light and not important) whereas it's the other way around in static sites (I'll get used to it) - another concern is that authors would get into a I go back to @teoli2003 's ideas to restrict it to certain page types - that would help mitigate some of the concerns I have I think 👍 |
Beta Was this translation helpful? Give feedback.
-
This is a bit vague at the moment but I think it is potentially useful.
The problem
We quite often want to say that a collection of pages is an ordered set, in which we expect the reader to start at the first and progress through to the last.
Examples of this:
Guides under Web/API are also ordered, although it's less clear there. Typically we want to start off with "Using the XYZ" API, present common usages, then move into more niche usages in later articles.
So the main thing here is that we want to present these guides in a certain order (for example in sidebars). We generally do this by listing them in various spots, like in the sidebar macro itself or in another config file like GroupData.json.
Another thing is that we want to provide Next/Previous links in the articles. We do this by making authors add the relevant macro calls at the tops and bottoms of the articles, passing the next/previous links as arguments.
In some cases we also want to list all the articles in a series, as we do in the Learn area for example: https://developer.mozilla.org/en-US/docs/Learn/Getting_started_with_the_web/JavaScript_basics#in_this_module . We do this, again, manually, by adding a ist of links.
There's a lot of duplication here! Especially for Learn we are duplicating this structure in the sidebar, in the macro calls, and hardcoded into each page. Keeping it all up to date is hard and we often make mistakes. It also leads to inconsistencies where we forget to include it in one page or another, or put the list in a different place, or format the links differently, or...
The solution
Other SSGs deal with this using the concept of "weight". You assign a weight to each article in a series, and the platform lets you order them by weight.
On MDN for now this might mean that:
Beta Was this translation helpful? Give feedback.
All reactions