Consider "Development" section in readme (if this repo gets more complicated)

[jcbhmr]

If/when things start happening with build processes, linters, config, etc. that means it's more complicated than just open it in the github web editor and change a few lines in the yml file, it'd be a good idea to add a "development" section to the readme to outline what tools are used, how things work, and in general serve as a baseline "dev tour" or "dev guide" so that in 6 months you can read it and get a high-level overview or something like that. Also would help with tinkerers and prospective contributors.

Here's some dummy examples

I also often use a wiki as a "dev docs" for more like architecture stuff, and then github pages for like user docs as you can tell from the "see more on wiki" links; but that's only for more complex projects

point is there's a gradient, and if/when things like #24 #19 and others happen we might be on the verge of needing such docs

[spenserblack]

This would probably belong in CONTRIBUTING.md, no? With CI to enforce.

[jcbhmr]

I view CONTRIBUTING.md for info on the contribution process so things like:

• a basic overview of how to clone, code, test, commit, and open PR
• any custom code styleguide stuff to fit in with the other code
• any commit conventions (gitmoji, conventional commits, etc)
• any special process to contribute (like LLVM doesn't accept PRs, they do things in separate way)
• any PR requirements (like agree to CLA, sign something, must have X Y and Z text, how workflow works, any tests that must pass, etc.)
• what to do if you just have a question/idea but don't actually want to write code

---

I sort of have three audiences in mind when writing a readme:

• Users: people who just want to use the thing. They like examples, docs, etc. The "Installation" and "Usage" sections of a readme are for them. If there's a GitHub Pages site, then it's usually designed for users.
• Tinkerers: people who want to see how the thing works, and probably want to build it themselves. But they don't necessarily want to contribute changes back. They like outline documents, build instructions, code comments, etc. The "Development" section of the readme and a developer GitHub wiki are what I usually write with them in mind.
• Contributors: people who want to suggest ideas, write code, or help the project. They like conventions, walkthroughs, pointers to ask questions, styleguides, encouraging language, etc. This is who I usually write CONTRIBUTING.md with in mind. This group is a subset of the Tinkerers group, so they also use the developer wiki/"Development" section of the readme.

That's kinda how I think of things. I should add this to my STYLE.md file lmao

edit: I did: https://github.com/jcbhmr/.github/blob/main/STYLE.md#how-i-write-docs

[spenserblack]

The way I see it, not all tinkerers are contributors, but all (code) contributors are tinkerers 🙂
I go to CONTRIBUTING to know

• What interpreters/compilers I need
• What versions of these interpreters/compilers I need
• How to test and build

Personally, I'd be a bit confused to if these things weren't in CONTRIBUTING, but in the README (unless "contributing" was just a section of the README). And, yes, we could document these in multiple places, or have CONTRIBUTING link to ./README.md#development, but I think tinkerers would be smart enough to figure out that they can find development instructions in the CONTRIBUTING file 🙂

IMO a good CONTRIBUTING.md file is structured like this:

• Submitting a bug report or feature request*
• Submitting a code change
  • Development
    • Code style (document EditorConfig, linters, etc. here)
    • Building (if necessary)
    • Testing
  • Commit style

* Honestly, while the "submitting an issue" section is really common, it seems pretty unnecessary to me as long as we have good issue templates/forms.

If things get really complicated, then there can be a HACKING.md document, but I highly doubt we'll ever need that.

But I'd like the README to follow the 80-20 rule: the majority of readers are users, not tinkerers. The README should target the majority, and not get bloated with info only relevant to the 20%.

[jcbhmr]

But I'd like the README to follow the 80-20 rule: the majority of readers are users, not tinkerers. The README should target the majority, and not get bloated with info only relevant to the 20%.

You're absolutely right! That's what the dev wiki is for 😉 (which incidentally is why I was in the market for a GitHub wiki action in the first place)

like this kinda https://github.com/devcontainers-contrib/features/wiki/README

then there's a smallish "Development" section in the readme

[spenserblack]

Yeah, that looks good to me! I was just getting nitpicky about putting instructions like npm test in the README when we're making a CONTRIBUTING.md.

So I think CONTRIBUTING.md can be high-level (we use prettier, etc. etc.), and we can have a contributing wiki page that goes deep into details, like how to install prettier.