Idea: use Wikis

[trsvchn]

GitHub Wikis

The idea is to use Wikis to store README files. But I'm note if it possible to use yaml files

GitHub provides a free repo for storing docs related staff for your project: Wiki

it is a separete repo with versioning. you have to activate it, you can edit via browse and you can clone it:

git clone https://github.com/<git-username>/<repo-name>.wiki.git

About wikis on GitHub docs.

A real world examples

At ignite we use it to store a roadmap, maintainers notes.

Our colleagues at MONAI use it for the project management, they even store meeting minutes there, brainstorming logs etc.

check MONAI Wiki

[trsvchn]

Ok, sorry this is only for public repos

Wikis are available in public repositories with GitHub Free and GitHub Free for organizations, and in public and private repositories with GitHub Pro, GitHub Team, GitHub Enterprise Cloud and GitHub Enterprise Server. For more information, see "GitHub's products."

[rekado]

I always find wikis to be the wrong tool. They solve the problem of collaboration in that there's no gate keeping for contributions. That's a different problem from documentation, which should be written by those who can answer the question of why the code was written the way it is. We don't generally have the problem of herding dozens of contributors to assemble their little bits of wisdom into some sort of documentation. The problem is a) to have documentation and b) structure it so that it answers all questions before they arise.

Writing good documentation is rarely ever a problem of tooling. We want instructive prose, not pages upon pages of incoherent bits of potentially outdated or misleading snippets of text. I feel that wikis often lead to the latter and are not conducive to the former.