docs: Make the generated README more contributor oriented

[hillairet]

The current state of the README is quite hard to follow for people not familiar with the setup already.

One overall change was in the section titles and levels

• I used "How to ..." because it makes the purpose of the section clearer for the writer and the reader in my opinion.
• I adjusted the section levels because it was really not consistent.

Two very confusing sections:

1. The initialization of the github repo feels out of place because it happens once and is done by the person running scaf anyway. This should be in scaf itself, not in the generated README so I removed it
2. The management of secrets seemed to be jumping between sealedSecrets and .envrc file so I made two clean sections instead

To make the setup clearer for contributors I made two sections:

• one for setting up the environment, done once
• one for spinning up the app with commands that must be run every time

[daveoconnor]

That looks better, adding my notes as well as some comments on those based on your changes, from my own thinking when I was going through the older process, some of which still applies:

When the developer has a new project/codebase set up the docs are orientated towards the users who will come onto the project, rather than the user who needs to set up the project.

Maybe less the case now with these changes though maybe worth a second look all the same with that in mind and the idea later for maybe two sets of docs.

E.g. The docs say the user has to install Kubectl, Kind, and Tilt, but that user already has those set up. Not bad, but still a double take moment for me. Then the user goes on reading the "Initial Project Setup" instructions, which say to run make compile which fails because of 1password secrets

This would probably mean we'd want to move the .envrc step earlier in the doc with your change.

Thoughts: This needs refinement?
At a minimum adding 1password instructions would be better before make compile, but maybe there should be two README.md, one pared back one for the initial setup which most developers will look for of habit, and a second like README_CONTRIBUTORS.md, with the first README having an instruction the follows the rest of the setup to run mv README_CONTRIBUTORS.md README.md.

Distinct instructions might make them easier to change when updating the docs too.

Alternatively, a README.mdwith two distinct sections for setup/contributors.

Just some thoughts.

[hillairet]

I don't understand the last part of your comment:
In which situation are the steps of running scaf and setting up the generated project with make compile done by two people at two different times?
For me (and I could be totally wrong), whoever runs scaf will also setup (once!) the generated project all the way to where it can be handed off to any contributor, Sixie or not.
Therefore the project setup docs should be in the scaf root README and anything related to maintaining and developing the generated project belongs in the project's README.

Maybe we're on the same page and I misunderstood your last comments! 😅

[rochecompaan]

Nice! We need a few small updates.

[hillairet]

It would be good to merge sooner rather than later to avoid more conflicts and losing stuff.

[hillairet]

Merging with the idea that it's good enough to be in and might need to be improved in a later PR.

[daveoconnor]

with a newly generated project it seems like make shell-backend no longer exists, and make shell doesn't work.

[daveoconnor]

I've reopened a ticket about that #236