Update on the Content Organization Project

[pransh15]

Last year, we hosted several workshops and presented a clear plan to better organize MDN's content. The goal is to enhance content discoverability for users while making it easier for writers to focus on creating new content without being bothered by unclear categorization or placement challenges.

This year, the content team will begin implementing the proposed plan using a thoughtful, phased approach. We will start with smaller migrations, focusing on directories with low traffic and minimal pull requests. This will allow us to refine our processes, address any unforeseen challenges, and minimize disruptions.

As the project progresses, additional updates and changes will be rolled out in future phases. Feedback will play a critical role in shaping and adjusting our approach to ensure the best outcomes for both users and contributors. We will be discussing these here on discussions, on the MDN content call, and in our Discord.

We are currently finalizing the finer details and will share more specifics about the migration process once the plans are solidified. Thank you for your patience and ongoing support. Stay tuned for further updates!

[Rumyra]

Hey folks - I gave an update of where we’re at with content moving yesterday in the content call - I wanted to re-iterate here for anyone that missed it.

Project overview

The whole project has been split into phases - at this time we’re looking at one phase per quarter. Our goal for this quarter (before EO March) is to re-org 60% of directories. We will not be looking at larger more active directories such as HTML, CSS, JS & WebAPI - these will come in later phases.

Due to our work last week (see below) we will list the directories we are looking to move and give an estimate of when we will be moving them.

While we appreciate help and reach out if you’d like to, we do not expect it. This work is a little disruptive and currently myself, Brian & Vadim work on the same team in the same timezone so co-ordination is made easier due to this.

Changes so far

Last week myself, @bsmth & @pepelsbey started drafting small directory re-orgs. We started with the XML type directories as they are small and have little (no) open prs.

See an example here

We discovered and ironed out a few issues during this work:

• Sidebars - the XML type directories are quite dated and there are a lot of 'quicklinks' and html inserts for sidebars at the bottom of these pages. Due to the launch of Rari and the ability to author sidebars in content and include them in the frontmatter, we have started to do this slowly with each directory we've looked at so far. We had to update the frontmatter linter to allow sidebars to be declared in frontmatter. Changing sidebars to use this 'new way' was originally outside the scope of this project, and we will not be doing a pass on the whole of content at this time to update all of them at once, but due to the opportunity to rid some legacy ways of inserting links into sidebars (as above) we've created and moved the sidebars in the areas we were working on to use the new format.
• As per the original plan presented last quarter, we've introduced a new page type 'listing-page'. This is a very simple, low maintenance page, listing pages within an area, where a full landing page is not suitable, or not already available. We need a way to distinguish between landing pages and this much more stripped down page - there’s a case these pages could be automated, but that is outside the scope of this project at the moment. The listing-page type has been added to the linter and the contribution docs. We also have a template for this page type which we will add shortly.
• We tried to keep merge conflicts to a minimum by checking open prs before moving directories and after merging the prs we created. We experienced big merge conflicts between our own prs due to the redirects file having so many changes. It appeared conflicts on open prs were kept to a minimum. A learning from this is to schedule these prs and try to keep them open for the shortest time possible.

Next steps

• Outline the details of phase 1. Create a tracking issue with the directories we will move and when.
• Once we’ve got on top of this first part of work we will start discussing HTML, CSS & JavaScript, for which we’d appreciate input. Expect discussions to start around the end of this quarter as this will make up the work for Q2.

Once we’ve released a better schedule, let us know if you’re planning any big changes and we can coordinate with you.

Additionally talk to us if you have any conflicts you’re struggling with and we will help resolve them.

Let us know any feedback and thanks for your patience while this is happening!

[Rumyra]

Tracking issue for phase 1 of the project mdn/mdn#637

[dipikabh]

@bsmth and myself are starting to look at reorganizing HTML next. This is part of Phase 2 of the project, tracking via mdn/mdn#662.

[bsmth]

I've gathered some feedback & looked at previous discussions about API docs architecture and there's a Discussion here which outlines the current proposal: https://github.com/orgs/mdn/discussions/796