README Refactor

[ElectronicsArchiver]

➜ Preview

• Taking #3 into account.
• Moved Google EC docs into separate file.
• General Formatting

[ElectronicsArchiver]

Besides my pull request I was also wondering:

• If you would turn on Discussions
• Add tags to the repository
• Link the framework website in the repo info tab
• Disable unused features like Packages
• If you were planning on tidying up the repo content by placing all Source files into a Source folder, as not to clutter the root folder?

[Risae]

I would rather recommend using collapsible markdown instead of moving the text to another file, but i agree that the current readme is ugly to look at.

Collapsible markdown example: https://gist.github.com/joyrexus/16041f2426450e73f5df9391f7f7ae5f

[ElectronicsArchiver]

Sure, will do.

I know how to use them, still thank you for linking an example :3

[DHowett]

If you were planning on tidying up the repo content by placing all Source files into a Source folder, as not to clutter the root folder?

Given that this project is based on the upstream Chromium EC, it would be better to keep their repo layout. It’s pretty logically organized: it’s a repository of code, so it wouldn’t be meaningful to hide the code another layer deep. :)

[Risae]

If you were planning on tidying up the repo content by placing all Source files into a Source folder, as not to clutter the root folder?

Given that this project is based on the upstream Chromium EC, it would be better to keep their repo layout. It’s pretty logically organized: it’s a repository of code, so it wouldn’t be meaningful to hide the code another layer deep. :)

That honestly just sounds like a lazy excuse not to put in some work and use best practices in repository management, don't you agree? And the points that @ElectronicsArchiver brought up are valid. Here's a very good example on how a public repository should look like, check it out :) https://github.com/winscp/winscp

[ElectronicsArchiver]

it’s a repository of code

So? Just because the repos focus is a software project doesn't mean the root folder has to be stuffed with source code or folders thereof.

In fact, no repo should do that regardless of content, considering that any project should have documentation and most contain resource / wiki and archival files as well.

Besides, having that many items in the root folder significantly pushes the README down the page, making navigation of the README and attached documentation more of a drag.

This would be like filling your apartment with work related boxes saying, well I'm a X so it's pretty logical to have all of these things right around me. There are cupboards, closets and storage rooms for that.

The upstream part however is a good point, though I don't think it's impossible to just direct it into a subfolder I presume? Considering that the structure of the source folders wouldn't change..

---

Oh Risae just commented, well I'll still post it.

[junaruga]

That honestly just sounds like a lazy excuse not to put in some work and use best practices in repository management, don't you agree? And the points that @ElectronicsArchiver brought up are valid. Here's a very good example on how a public repository should look like, check it out :)

I don't think it's a lazy excuse. When there is the upstream of this repository, it's important to minimize the difference between this repository (downstream) and the upstream to make the backporting easier. When I want to fix a part of the upstream in a downstream repository, I always try to fix the part on the upstream first, then backport it to the downstream. This approach in the contribution is called "Upstream First". You can search by "Upstream First", then you can find some documents.