Create a default README.md

[christian-bromann]

Currently all Enhance projects created via e.g. npx "@enhance/create@latest" ./myproject -y don't have any README.md files nor CONTRIBUTING.md. I wonder if it makes sense to create a very simple default file that includes some basic best practices and placeholder for user to fill out.

wdyt?

[colepeters]

Thanks for bringing this up! I could see this being really useful — perhaps including an overview of the directory structure at a minimum, and then maybe linking out to specific docs for more specific concerns (styling, data, API routes, etc)? Are there any particular areas you'd like to see mentioned in the default readme?

Regarding a contributing.md file, Enhance is actually several packages working together, so a contributing guide in the starter project may be a bit misleading, as it would only pertain to contributing to the starter project itself. Not sure if that's what you had in mind?

[kristoferjoseph]

I'm open to this but didn't do this from the get go due to some user concerns.

The thinking here is that this is generated for a user not for the Enhance team.

We don't want to create work for a user by making them have to delete files before publishing.

With that said having a README is a best practice so 🤷‍♀️

[christian-bromann]

Not sure if that's what you had in mind?

One could argue it is best practices to have a place for putting developer documentation. So every user that creates an Enhance project could get a CONTRIBUTING.md which documents some of the workflows that are defined in package.json.

perhaps including an overview of the directory structure at a minimum, and then maybe linking out to specific docs for more specific concerns (styling, data, API routes, etc)?

Sounds like a good idea!

Are there any particular areas you'd like to see mentioned in the default readme?

Either a reference to the contributing guidelines or we put these into the README.md directly.

We don't want to create work for a user by making them have to delete files before publishing.

Why would users want to delete the Readme.md file? Note, this file is meant to be created as part of the new Enhance project. Currently these projects have no readme file and requires users to create one.

[colepeters]

One could argue it is best practices to have a place for putting developer documentation.

For sure! For Enhance, we have all our docs at https://enhance.dev/docs, and we also include a link to these docs on the starter project's default index.html so users can see it when starting up a fresh project. Of course that's not to say we can't also include some helpful information in the starter project's readme, it's just a matter of determining what that information might be.

So every user that creates an Enhance project could get a CONTRIBUTING.md which documents some of the workflows that are defined in package.json.

I may be a bit confused here. In my experience, a contributing.md file provides information on how to contribute to the source project itself, rather than documenting workflows like start and lint for the generated app. That's why I was saying that this file may not be useful in new projects generated via enhance/create, because there's not much to contribute to enhance/create itself, if that makes sense. Maybe I'm unclear on what you're suggesting, though?

Sorry, I just realized you're likely referring to a placeholder contributing guide for the created project, not for enhance/create itself. 😄

[christian-bromann]

To clarify: if a user runs npx "@enhance/create@latest" ./myproject -y, we can assume they start a journey to build an application and maintain this project for the foreseeable future. Now a new Enhance project has the following structure:

.
..
.arc
.enhance
.gitignore
app
node_modules
package-lock.json
package.json
prefs.arc
public

I assume it is very likely that in order to successfully maintain the project and share it with peers, a user might want to have a README.md file and also a CONTRIBUTING.md that explains some of the workflows to work with this Enhance project.

So these markdown files are meant to serve the Enhance developer that creates a new Enhance project and not the Enhance maintainers (the folks contributing to this repository). Does it make sense?

[colepeters]

Makes sense, thank you! :)

[kristoferjoseph]

I am a go for a default README that has the default project structure outlined and a link to the docs and a hard pass on a CONTRINBUTING file.