Let's reorganize the CSS docs

[wbamberg]

The structure of the CSS documentation isn't very clear. I think it its original conception the docs had a (completely?) flat directory structure, and macros relied entirely on tags to organize them. Over time subdirectories have been added, but it's still mostly flat.

In general this makes it hard to see what we have, or how our docs are organized. Which module pages do we have? Which are missing? Which CSS function pages do we have? It's hard to get a quick answer to this.

It also causes specific problems when features in different parts of the language have the same name. For example, we have the color property and the <color> data type: because they have the same (normalized) name, we have to have a _value suffix on the data type:

https://developer.mozilla.org/en-US/docs/Web/CSS/color
https://developer.mozilla.org/en-US/docs/Web/CSS/color_value

Not all data types get this suffix, only those that happen to have another language feature that has the same name:

https://developer.mozilla.org/en-US/docs/Web/CSS/image <- no suffix
https://developer.mozilla.org/en-US/docs/Web/CSS/position_value <- oops, need a suffix!

Similarly we have the fit-content keyword and the fit-content() function:

https://developer.mozilla.org/en-US/docs/web/css/fit-content
https://developer.mozilla.org/en-US/docs/web/css/fit-content_function

...and again it is hard to predict which functions will get the _function suffix.

Proposal

To begin with I'd like to propose the following hierarchy, based on (but slightly simplifying) the set of CSS page types: https://developer.mozilla.org/en-US/docs/MDN/Writing_guidelines/Page_structures/Page_types/Page_type_key#css_page_types

css/reference
    /at-rules (with descriptors underneath their at-rule, and media features under @media)
    /combinators? or should they be under selectors?
    /functions
    /keywords
    /modules
    /properties
    /selectors (including pseudo-classes and pseudo-elements)
    /types

The rest of the pages are all guide pages or landing pages, and could stay where they are (there is often a sensible hierarchy there already, e.g. https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Flexible_Box_Layout#guides).

We'd have to figure out how to update all the macros so this still works. In particular this would break cssxref.

[schalkneethling]

Tagging @mdn/yari-content

[SphinxKnight]

cc @mdn/localization-team-leads since such a move might trigger a large number of "sync translated-content" PRs

[teoli2003]

I like the idea to have a less flat hierarchy (with @Elchi3, we were able to unflatten a bit the API almost a decade ago).

We'd have to figure out how to update all the macros so this still works. In particular this would break cssxref.

I'm worried here that while trying to solve the unpredictability of adding _value or _function, we are instead adding complexity for every link by breaking {{cssxref}} (Replacing complexity for a few by complexity for all).

I can imagine fairly easy solutions for sidebar macros, but how do you plan to use {{cssxref}} in this new world?

I think you are right that this is the key problem, but what would be the solution? Immediately, I can see two:

• removing cssxref and using Markdown links,
• adding a parameter, optional unless there is ambiguity

The first one means any author needs to know the hierarchy, the second one is _function, or _value in disguise.

Maybe there are more solutions to consider here…

(I would like to avoid the complexity of jsxref, where rather to find the right parameter set, I prefer to use a Markdown link instead)

[teoli2003]

My opinion (feeling?) is that we should eliminate all link macros.

But we should do it with an additional change: instead of using the production links (/en-US/docs/X/Y/Z), we should use the GitHub links (/files/en-us/x/y/z), and Yari should replace them with the production links (using the slug in the document).

That way, we can navigate inside the GitHub UI, and more importantly, the content code becomes more independent of the production site structure.

I'm not saying we should do it now, just that I'm ok with getting rid of cssxref (and jsxref).

The link macros were created because it was difficult to style links correctly in an HTML-storage world, not because the URL was difficult (The information architecture was almost an all-flat hierarchy back then). This reason disappeared with our migration to Markdown.

[Graywolf9]

It looks like

1st: change cssxref("position") to cssxref("types/position") could be the direct solution for the main problem: reorganize
2nd: consider the migration of link macros to markdown urls
3rd: change the url from /lang/docs/ to /files/lang/

[wbamberg]

My opinion (feeling?) is that we should eliminate all link macros.

💯

But we should do it with an additional change: instead of using the production links (/en-US/docs/X/Y/Z), we should use the GitHub links (/files/en-us/x/y/z), and Yari should replace them with the production links (using the slug in the document).

That sounds like a good idea.

[OnkarRuikar]

That way, we can navigate inside the GitHub UI, and more importantly, the content code becomes more independent of the production site structure.

Also, it will be easy to create links using intellisense of IDEs:

[teoli2003]

Yes, "intellisense" of VSCode just got better. It would be great to use the "generic" tools that IDE makers build in their products.

[rachelandrew]

I'd probably suggest grouping some of this under /values, these seem all to be values (see https://www.w3.org/TR/css-values-4/)

• keywords
• functions
• types

Seems a bit odd to not group them as values, granted that doesn't help with fit-content, but I think that's a bit of an exception. It would fix issues such as color (property) and <color> (value).

Combinators are selectors, and so should be included with selectors.

[wbamberg]

The organization I proposed really just reflects how we already implicitly categorize things on MDN at the moment. We already talk about "CSS data types" and "CSS functions" as different kinds of thing, and use different notation for them, and (implicitly, but should explicitly) have different page structures for them, and have different landing pages for them (functions, types). So it's just making that distinction more visible.

But if this is misleading I'm happy to have alternatives. It seems like a pity to go to all this work and not fix the naming collisions issue though.

[wbamberg]

One thing we might do is have "values" and then the different value types underneath them:

css
   /reference
             /values
                    /functions
                    /keywords
                    /types

...which is intended to reflect https://www.w3.org/TR/css-values-4/#component-types , except for:

• point 3, which is covered by "properties"
• point 5, which AIUI includes things like <baseline-position> in https://developer.mozilla.org/en-US/docs/Web/CSS/justify-items#formal_syntax, and which usually don't get separate pages (when they do we call them "type").

[ramiy]

Related: mdn/browser-compat-data#10563

[Rumyra]

I really like this idea @wbamberg - thank you - and I agree with the proposed grouping.

It's slightly out of scope of the original discussion, but I also like @teoli2003 suggestion for replacing xref stuff with github links, I think we're getting to the stage where it's starting to make sense to have markdown links over the macros. However this should be considered as a separate task and a discussion that should involve @mdn/core-dev

Aside - we're starting work on a roadmap at the moment, so I'm going to reference this in that work

[teoli2003]

Moving away from the xref macros and having GitHub links could potentially be a joint MDN-OWD goal for 2023. (We would need a plan because it touches Yari, Kuma macros, and the content and we need to be careful)

[Josh-Cena]

Deprecating xrefs makes the source much longer, because I use the source text's length to roughly control the length of each paragraph. We could limit its use (for example, jsxref has four arguments but I only ever use the first two; we shouldn't allow HTML markup in the macro), but I find writing {{jsxref("Object.keys()")}} much more enjoyable than copying the long URL or file path and inevitably duplicating the names Object/keys (once in link text, once in link target).

[estelle]

css/
    /atrules
          /font-face/ (css-at-rule-descriptor pages related to font-face go here, other css-at-rule-descriptor pages nested similarly)
          /media/ (css-media-feature pages go here)
    /functions (only a few, if any, `css-function` pages; possibly the trig functions?)
    /guides     (`guide`, `css-guides` and `landing-pages`, none nested, unless it is a literal series with back and next buttons)
    /keywords (some `css-type` pages; anything writing without `<>` that doesn't fall under a `<>` type; ncluding flags, some guide pages (like actual-value), ident, etc)
    /modules (`css-module`.  currently some are listed as `guide`, but won' t be next quarter)
    /properties    (`css-property` and `css-shorthand-property`)
    /selectors    (`css-pseudo-class`, `css-pseudo-element`, `css-combinator`)
    /types     (`css-type`, anything written as `<css-type>`)
           /image
                 /gradient  (gradient `css-function` pages go here)
                 /image-set
          /filter (the 10 or so filter css-function pages go here
          /blendmode (the 16 or so css-function blend modes go here)
          /color/ 

I don't know where custom properties would go.
Would customColor go under color or keywords?

Note there are very few functions, if any, are under /function. Rather, functions are under their 'type'.
no dashes in blendmode, atrule, etc. dashes only in property names or keywords as written in CSS as a value.

[ramiy]

We have two different function types:

• CSS value functions - https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Functions
• CSS at-rule functions - https://developer.mozilla.org/en-US/docs/Web/CSS/At-rule-functions

Two different types of functions. I don't think we should mix them because there are identical function names.

[ramiy]

    /types     (`css-type`, anything written as `<css-type>`)
           /image
                 /gradient  (gradient `css-function` pages go here)
                 /image-set
          /filter (the 10 or so filter css-function pages go here
          /blendmode (the 16 or so css-function blend modes go here)
          /color/ 

I think that we need to move all the image, filter, blendmode, color to simple functions.

[estelle]

Been thinking about this. and looking forward to it.

-- /CSS/
   --  /descriptors/  
   --  /language/ 
   --  /modules/
   --  /properties/
   --  /selection/ (or /selectors/) 
   --  /values/  

with prefixed features nested in subdirectories, so:

-- /CSS/
   --  /descriptors/  
   --  /language/ 
   --  /modules/
   --  /properties/
       -- /prefixed/
   --  /selection/ (or /selectors/) 
       -- /prefixed/
   --  /values/  
       -- /prefixed/

where:

• descriptors includes css-at-rule and nested css-at-rule-descriptor. example:

   --  /descriptors/  
        -- /font/
             -- /font-family/
             -- /unicode-range/

• language includes concepts, currently guides, like syntax, block formatting content, box model, used value, etc)
• modules includes all the css_xxx files. Subdirectories include guides.
• properties includescss-property and css-shorthand-property
• selection includes everything that comes before the {} in a selector block, includingcss-pseudo-class, css-pseudo-element, css-combinators)
• values includes data types along with their keywords and functions. Includes css-type, many css-functions, and keywords, like initial, which are currently guides.

   --  /values/    
        -- /image
             -- /gradient  (gradient `css-function` pages go here or nested further)
             -- /image-set
        -- /filter/ (the <data-type>)
             -- /sepia/ (the `css-function`s of that type)
        -- /color/ 

There should NOT be a top-level function directory, as function notation is found in selectors and values

[dipikabh]

Hi all, thanks to everyone who attended the Editorial on May 12 and shared initial thoughts on the CSS reorganization plan. It is based on the proposal shared in this discussion and takes into account other comments shared so far.

This is a Google Sheets file. For anyone interested in this topic, please request access to the file. You're welcome to add a tab to the sheet to share your feedback, suggestions, questions, or concerns. Or you can share your comments here. We're aiming to collect all the feedback over the next few weeks before finalizing the folder structure.

(For a quick visual of the proposed structure, I’ve also shared a preliminary tree layout here: https://gist.github.com/dipikabh/5b5f5be5ad2ce0eaf470bf48915cf186)

[chrisdavidmills]

Overall, I really like the proposed CSS reorg tree, @dipikabh. It certainly organizes everything much better and makes it easier to find existing pages you want to work on, or new pages you want to figure out where to put. I appreciate the addition of a specific how-tos section for locating pure task-based guides that potentially span across modules.

I agree with most of the choices you've made here. I did have a few queries and points:

1. I think this was asked before, but — I'm assuming you are intending that we will have a landing page for each directory, e.g., types, keywords, at-rules, reference, guides? I would be in favor of this, but I also think we should look for ways to automate them where possible, at least partially. For example, the CSS functions index page is currently a bit annoying because every time you add a new function, you have to add it to this page, in two places, manually.

2. What do you envisage going in tutorials, as opposed to guides? In my mind, "how to use this feature" articles inside topics (like CSS, JS, APIs, HTML, etc.) would mostly take the form of guides, and tutorials would be aimed more at beginners to introduce them to an overall topic area. In the case of HTML, CSS, and JS/APIs at least, the learn web development area of the site provides this function, and we'd need to be wary of duplication. Unless, of course, in these cases, the tutorials section would just link to the learn tutorials?

3. I think the most controversial part of this is going to be moving the guides under a separate guides section versus keeping them under their respective module pages, especially considering @estelle just did a bunch of work moving them under modules ;-) What is best for the user and the site authors, I think, depends on how intuitive each approach is.

Do people naturally think of CSS topics per module, or per use case? I think the two are sometimes the same (for example, filter effects, or fonts), but sometimes the modules are not very intuitive in terms of what use cases they solve (e.g., basic user interface or fragmentation). I therefore think it would be more useful for the guides to be in a separate place, but we should think carefully about the topics, and not just have them be the same as the modules. For example, we could organize them under Layout, Positioning, Filters and blending, Animations and transitions, CSS for language directions, or somesuchthing.

To be clear, I don't think this is a reason not to have CSS module pages, as some people will want to browse features by module. I just think they should be additional to the hierarchy.

Of course, this is just my opinion. I think we should do some more research to help make this decision. This doesn't have to hold up the whole reorganization. We could go ahead with the rest of the reorg, and leave the modules only versus modules and separate guides decision till later.