README.md is too big. What if it was possible to separate content into multiple .md files?

[AmineAouragh]

I noticed that the README.md is too big.

What if it was possible to have all the content structured in separate .md files inside a system-design-101-content parent directory?

Here is an example from the roadmap.sh repository.

That way we could have each topic separately with its own subtopics and own pictures. Cause I saw that even the images directory has all images in the same place instead of grouping related images depending on topics in separate directories.

A lot easier for contributors to fix anything that need to be fixed or add anything to any topic... and even for readers.

I will think about an easy way to "implement" that and I am open to work on it.

[tranquanghuy0801]

Agree with this. I think splitting README into sub-folders would be very helpful to both readers and contributors.

[MrOnlineCoder]

I personally disagree, single README is much faster to navigate and easier to read - like a book, I finished one section, and immediately can proceed to next one. Also there is no delay between loading each file separately, at least on Github UI. Or, otherwise, maybe it's possible to perform splitting in the repo, but run a CI/CD or other pipeline that will combine all files into one, so everyone can use whatever method they prefer

[hrodrick]

What about a link "Go back to index" at the end of each section that scrolls up to the table of contents? That would make navigation easier

[AmineAouragh]

@MrOnlineCoder but how about for contributors? it's much easier if you have separate subfolders so you can include changes in only one place and won't have to scroll through a giant README.md file, also commits would be separated depending on which files were updated.

You can have a look at the roadmap.sh repository I linked to above.

Also a README.md is supposed to be a presentation and description about the repository.

What the project does. Why the project is useful. How users can get started with the project. That's all.

[MrOnlineCoder]

@AmineAouragh sure thing, working with such structure is easier, my point was just to have a possibility to still have a full README in the output

[AmineAouragh]

you mean even if there was a system-design-101-content parent directory with subfolders you would want to still have the same README.md file?

[MrOnlineCoder]

@AmineAouragh not exactly. Many projects have documentation in different formats - full HTML file, HTML file by sections, full PDF, etc. My point is to have something like README-BUNDLED.md which can be used by people like me that prefer that way of navigation. The internal or public structure of the files can be whatever

[AmineAouragh]

yeah that's what I meant @MrOnlineCoder

[martin-yin]

I think dividing the content into multiple md files can allow me to focus more on a certain chapter.