Reorganize files into a flat structure

[shainaraskas]

This PR reorganizes our files into a flat structure, and updates xrefs so all images and partials load as intended.

Confirmed IA is the same + previewed images + partials to make sure they rendered.

The flat structure is intended to:

• allow us to play with information architecture in future while minimizing file moves in the backend
• allow us to share certain resources that require relative paths easily
• adhere to the versioning structure we expect we will use (backporting TODO)

If we decide that this structure isn’t granular enough to navigate for our contributors, we can add additional subfolders later.

serverless      # the deployment type
├── pages       # mdx pages
├── images      # you get it
├── nav         # nav files for serverless
└── partials    # mdx included in other pages    

nb: the partials we currently have are only used in a single place. in my opinion, these could be integrated into the parent page.

[shainaraskas]

this file was moved here

[shainaraskas]

duplicate

[shainaraskas]

duplicate

[shainaraskas]

incorrectly detecting as a new file - caused by all of the widget files previously being identical.

[florent-leborgne]

Thanks! This is nice. I pulled it down and here are the first few things that crossed my minds (some of those are likely to be treated separately from this PR ^^'):

• it's great to have subfolders to gather images, navs and partials
• would we have several "levels" of partials? Right now this repo is limited to serverless, so our partials are limited to reuse between serverless files, but when there will be more and we reuse content between serverless and other things, or between other things, could this become an issue over time? Should partials be at the root instead?
• we already have a quite a few files while it's just platform and search for now. I'm still concerned with the idea of flattening everything under /pages while we could instead have multiple "pages" folders (same level) but different names to distribute the content more clearly, relative paths to shared resources would be the same. Do we want to rely on specific file naming conventions instead? Right now it may look manageable, but I'd like to put something in place sooner rather than later as we could expect this repo to grow quickly. For instance cloud-, es3-, kib- (for kibana platform features)? I also think this might not be very easy for contributors.
• having all flat makes me realize that our process for determining slugs is very manual, and there are already some errors/inconsistencies that look like they've been around for a while (like some /elasticsearch in the middle of /general in the nav). Should we flatten our slugs as well before things get unhealthy?

We can definitely merge like this, but it'd be great to think about some of these points fairly soon.
Thanks for all your work!

[florent-leborgne]

Actually, building this PR locally, I noticed that the general docs are missing some files. It looks like an older version of the doc set. I don't see content added over the last couple of weeks. I'll try to locate an exact date.

Edit: For content from staging-serverless-general-docs, it seems that this repo has everything up until commit 8fac5954500400341447c21c22efa8486281361a on April 22. Changes that came after that commit are currently missing.

Edit2: Fixed, thank you 🙏

[shainaraskas]

hey @florent-leborgne! I've fixed the history issue (thank you!). In reply to your other comment:

• would we have several "levels" of partials? Right now this repo is limited to serverless, so our partials are limited to reuse between serverless files, but when there will be more and we reuse content between serverless and other things, or between other things, could this become an issue over time? Should partials be at the root instead?

This is definitely a concern. The partials are sitting in this serverless folder so they can be hypothetically "versioned" and "backported" with the serverless content. I think keeping a group of unversioned partials and images a level up (or in a common folder that's a sibling to the serverless folder) would work from a technical POV, but I wanted to avoid making assumptions about what content would be shared / how we want to approach versioning of partials overall.

• we already have a quite a few files while it's just platform and search for now. I'm still concerned with the idea of flattening everything under /pages while we could instead have multiple "pages" folders (same level) but different names to distribute the content more clearly, relative paths to shared resources would be the same. Do we want to rely on specific file naming conventions instead? Right now it may look manageable, but I'd like to put something in place sooner rather than later as we could expect this repo to grow quickly. For instance cloud-, es3-, kib- (for kibana platform features)? I also think this might not be very easy for contributors.

I agree with you that this looks pretty overwhelming. Part of the motivation in flattening the structure is to avoid assuming what is going to be grouped together/what mental models people will use in the future. @chriscressman has talked a lot about this, but an imperfect summary is that we want to assume that people won't be using the file name / repo folder structure to find content, but instead using some sort of file identifier to find it through search (or jump to the file using an "Edit this page" button like the one below).

That being said, I think that naming conventions are a lightweight way to add context at a glance so that might be a good way forward in the interim. These don't map exactly to the old folders we had, so it would be a manual effort. Will think more about this.

• having all flat makes me realize that our process for determining slugs is very manual, and there are already some errors/inconsistencies that look like they've been around for a while (like some /elasticsearch in the middle of /general in the nav). Should we flatten our slugs as well before things get unhealthy?

Great callout. Was just talking to someone about how the slugs are essentially arbitrary. I think we need to define a pattern around this as well. Not sure if we have redirect support at the moment, so we'll need to approach that cautiously. We have redirect support, but for perf reasons we should probably try to avoid changing these too much.

[lcawl]

🚀