[Proposal] Encourage README.md files for sub-directories

LLVM Project
1

The LLVM ecosystem is so large that every few years I discover something new in it that I never even heard about. And sometimes, those things are just files somewhere, or a new directory with a name that sounds reasonable but looking at the code, it could be multiple things.

It would be nice to have a simple README.md that Github shows nicely at the end of directories, as a helper (on browser, editor, command line) to get the gist of what that code is about.

I’m sure the people who care about that are on top of maintenance and all, but the short in-place document would help others that aren’t actively developing that part, even if they’re a bit repetitive (ex. a similar one to every target, etc).

While there are README.txt files scattered around (and Github does show them on the web UI), some of them are so old that they are completely irrelevant by now.

Could I interest existing active developers to add/update their own bit to their own areas?

Could this be something for the developer policy (for new stuff at least)?

I imagine this would be even more helpful to new developers trying to make sense of the huge repository we work on, and hopefully lower the learning curve.

@tonic

10 Likes
2

I second this. For Clang Static Analyzer folks, there is a docker-based benchmarking tool but IMO not everyone utilizes it, perhaps because there is no straightforward documentation for it(?)
We can add one such README over there.

3

I think it’s an interesting idea to explore and to think about how it would be most useful. I do want to avoid duplicating information in multiple places just from the maintainability standpoint. For example, the top level README in llvm-project duplicates or even contradicts information elsewhere in our docs.

1 Like