Add read.me inside generated project

[jhomarolo]

Is your feature request related to a problem? Please describe. Since we have the herbsshelf, we should create a read.me as an example to show the user how to use Herbs.

Describe the solution you'd like A read.me file with instructions about how to use/config the project generated by cli

[jhomarolo]

I've added a basic readme file (#107) with substantial information about the CLI, but it's far from what it needs to be.

The documentation should be dynamic according to the options chosen and much more complete, explaining the entire structure of the generated files.

For now I'll still leave the issue open, because it needs a relevant contribution here.

[italojs]

If someone want to implement it, follow this instructions

to solve this issue, just go into readme.js generator and pass the props for the template like this so after this, receive the props like this

[othonvv]

I can take it

[italojs]

@othonvv we already have a read.me there, try to turn on it dynamic :) https://github.com/herbsjs/herbs-cli/blob/main/src/templates/readme.ejs

[jhomarolo]

@italojs do you have some examples about how the final read.me should be?

[dalssoft]

The current readme is too technical, not a domain driven... What could we do to make it more domain centric?

[jhomarolo]

I think the initial read.me should be about three things:

1. A tutorial explaining the code generated with CLI (folders structure, application architecture) and how to use the CLI (herbs update for example)
2. A tutorial explaining the application and how to use (start, debug, migration, test)
3. A documentation about the application at the modeling and domain level

What do you think @dalssoft , @italojs ?

[dalssoft]

I would go on a different direction, a more domain centric, less technical centric. Also, the template should direct developers towards domain centric documentation.

Suggested template:

# [Name of the project]
It should be something human readable, not technical.
✅ Billing System - Platform
❌ HALBill.Plat

[What it does]
It should briefly capture the main reason why this system exists.
✅ This microservice manages all the recurrent and usage based billing for the company.
❌ This microservice uses Postgres 14.23 and some message queue to handle billing.

[What it doesn't do (optional)]
It is important to explain here if it is common for people to misunderstand the system purpose and its features 
✅ This system doesn't process payments, it only generate bills. Check the Payment System for that.

# Main features
It should be a list of top 3 or 5 features or use cases.
✅ - Products list (CRUD)
✅ - Product usage billing management
✅ - Product recurring billing management
✅ - Product billing closing
✅ For more features: [link to project's Herbs Shelf]

❌ - REST and GraphQL APIs
❌ - Serverless
❌ - Handles 1000 transactions/second

# Using

To start the project for the first time:

    $ npm install
    $ npm run knex:migrate
    $ npm start

# Technical Requirements

- Node 16
- Postgres 14

Any other suggestions?

[italojs]

@dalssoft the suggestions is great except by #main feature session, I think it must be present in the read.me because it conflicts with the herbs usacases doc

@jhomarolo I agree with herbs-cli session is super important we reinforce the idea to use the CLI

Another suggestion is: have a session about documentation too, like

Documentation
You could find the < project-name>.docuemntation accessing localhost:3000/herbshelf
<doc image> 

@othonvv pay attention to generating a dynamic read.me, e.g: Talk about migration when the project use postgress, dont talk about not included infra layers...

[othonvv]

@italojs how does this documentation section should work on practice? Just briefing the user about herbshelf benefits and how to use it?

[dalssoft]

@othonvv any update on that?

[othonvv]

@dalssoft not yet

[herbsjs-robot]

:tada: This issue has been resolved in version 2.10.0 :tada:

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot :package::rocket: