Exploration: How to visualize what is where?

[spier]

When I started reading the MVG I had a bit of a hard time figuring out what is where, and what each file is meant to be used for.

I have some ideas but I don't fully know where I am going with this so rather than sending a PR for it right away, I am exploring the options here.

Idea 1: Formatting the two main folders in the README slightly differently

The README could make it more obvious that the main structure are these two folders.

It could look similar to this:

There are two folders:

• org-docs: Provides top-level organizational governance and polices for a technical steering committee (TSC).
• project-docs: Provides a template for individual project governance, subject to the polices and oversight of the larger organization.

Idea 2: Tree structure

Listing the main files in the README would allow to explain where to start, and what the purpose of each file is.

For example:

org-docs/
├── ANTITRUST.md - ...
├── CHARTER.md <= Start here
├── CODE-OF-CONDUCT.md - Code of Conduct based on the Contributor Covenant.
├── STEERING-COMMITTEE.md - Lists the voting members of the Steering Committee
└── TRADEMARKS.md - ...

project-docs/
├── CONTRIBUTING.md - ...
├── GOVERNANCE.md <= Start here
├── LICENSE.md - ...
└── MAINTAINERS.md - Lists the Maintainers of the Project

Alternatively one could add a new README.md file to each of the folders.
Those would serve as index pages, explaining what each file is meant to be used for.

So much for now. Looking forward to hear your thoughts on this.

[royaljust]

Thanks @spier - I agree this would improve usability. This feedback echos feedback in the discussion section of Issue #1.

I'm partial to the file structure idea. I'll play around with a few concepts and come back for further discussion.

[jberkus]

So, @royaljust and I discussed this today, and for really small, single-repo projects, I feel that we need an option for them to use only the "project" portion plus the files that apply regardless of project/org level. That is, specifically ignore org-docs/charter.md, since there's no point in having 2 levels of governance for projects that have 4 contributors.

[spier]

Yeah, I was also wondering if the org-docs and project-docs are always meant to be used in combination or not. So clarifying that further will be good.

In either of these cases though (project-docs only or all docs), do you have suggestions for how one could provide an overview for readers so that they can more easily figuring out what is where, and what each file is meant to be used for?

[jberkus]

Documentation?

[spier]

Yeah documentation for sure.

What I meant was more how specifically one could document this, as the top of this issue was exploring ⬆️

[xiaohk]

It might be helpful to add some example organizations who implement MVG, such as InterpretML, Fairlearn.