Clarify USPs in README

README.md

@@ -1,50 +1,59 @@
-# Basecode - The fastest way to create a web app
+# Welcome to Basecode!
 
-Basecode is a full-stack platform for creating web apps using Kotlin, Spring Boot, GraphQL, React (NextJS) and
-Postgres. The platform consists of several generators to generate the basic structure of web applications, based on
-often used technologies within IT. The goal of Basecode is to provide its users with a productive tool to
-create lean, decoupled code with a solid foundation.
+We are excited to have you here!
 
-Basecode is fully open source ([MIT](LICENSE.md)).
+Basecode is a full-stack platform for creating web apps. The platform consists of several generators to generate the
+basic structure of your web application.
 
-⭐ If you like Basecode, please consider giving it a star. Your support can help the project grow and deliver exciting
-features.
+(Code generated by) Basecode is:
 
-<a href="https://www.youtube.com/watch?v=rx9xL0nhot8"><img src="video-button.png"></a>
+- **Productive**, as it allows you to generate authentication and CRUD functionality with 1-N relations, including
+  migrations, GraphQL schema files, unit tests and integration tests.
+- **Maintainable**, as it provides a package-by-feature structuring approach, GraphQL communication and domain events
+  between different aggregates, so you get a highly decoupled and extensible architecture.
+- **Incremental**, as it allows you to start with almost no code. Then, once you're ready for the next step, add
+  scaffolds, authentication, a frontend and more at your own pace.
+
+Basecode generates code consisting of:
 
-Top reasons to use Basecode:
+- Kotlin / Java (coming soon)
+- GraphQL
+- Typescript + React (through Next.js)
+
+Finally, Basecode is open source ([MIT](LICENSE.md)).
+
+⭐ If you like Basecode, please consider giving it a star. It would mean the world to us! Your support can help the
+project grow and deliver exciting
+features.
 
-- **Deliver faster**: Basecode allows you to build your product drastically faster than if
-  you would write all your code manually. Furthermore, it allows you to shorten your feedback
-  loop, meaning you can pivot faster and deliver the product that your users want.
-- **Solid, scalable foundation**: instead of spending months on design decisions that
-  do not add business value, you get a solid, highly scalable foundation to build upon.
-  Basecode combines Kotlin, Spring Boot, React (Next.js) and GraphQL in such a way that
-  the code remains maintainable, testable and scalable, so you don't have to worry about
-  design details.
-- **All you need, but nothing more**: when you start out with Basecode, there are only a
-  few lines of code. As soon as you need a feature, you can easily add it. If you don't need
-  Basecode, however, it completely gets out of your way.
+<a href="https://www.youtube.com/watch?v=rx9xL0nhot8"><img src="video-button.png"></a>
 
 ## Installation
 
-The following software needs to be installed on your machine before you can use Basecode effectively:
+In order to use Basecode, make sure you have the following software installed:
 
 - Go 1.16 or later
 - JDK 21 or later
 - Node 18 or later
-- Docker (for setting up a development database)
+- Docker
 
-Install Basecode using the following command:
+You can install Basecode using the following command:
 
 ```shell
 go install github.com/wnederhof/basecode/cmd/basecode@latest
 ```
 
 ## Usage
 
+For each of the following commands (except for `new`), you can use `-o` to allow overwriting existing files and `-d` to
+delete the specified set of files. Note that the flags go after `generate`.
+
+For example: `basecode generate -o scaffold Post title contents:string`
+
 ### Create a New Project
 
+To create a new project, simply type:
+
 ```
 basecode new <groupId> <artifactId>
 ```
@@ -102,42 +111,51 @@ Available types:
 - datetime
 - boolean
 
-# Example
+# Starting the program
+
+In order to start your newly generated program, you need to:
+
+- Run `docker-compose up` in the `<artifactId>-server` directory to start up a local database
+- Run `./mvnw spring-boot:run` in the `<artifactId>-server` server to start the backend (or launch the Application in
+  your IDE)
+- Run `npm install` in the `<artifactId>-web` directory to install the frontend dependencies
+- Run `npm dev` in the `<artifactId>-web` directory to start the frontend development server
 
-When you want, for example, to generate a blog, you can do that as following:
+# Blog Tutorial
+
+Let's discuss how to create a simple blog application.
+
+First, create a new application called `blog` and `cd` into it:
 
 ```
 basecode new com.mycorp blog
 cd blog
-basecode generate scaffold Post title contents:text
-basecode generate scaffold Comment postId:Post contents:text
 ```
 
-Most generators specify the following parameters:
+Next, let's generate scaffolds for the Post and Comment entities.
 
 ```
-  -d, --delete
-  -h, --help
-  -o, --overwrite
+basecode generate scaffold Post title contents:text
+basecode generate scaffold Comment postId:Post contents:text
 ```
 
-Here:
+Then, fire up a development database by running `docker-compose up` in the `<artifactId>-server` folder.
 
-- `delete` will undo the file generation. This command may also additional generate files, such as migration scripts for
-  dropping a previously created table.
-- `overwrite` will overwrite any existing files. When this option is not specified, Basecode will abort when a file is
-  about to be overwritten.
-
-## After Initialization
-
-After initializing your application, you can use `docker-compose up` to spin up a development database.
-
-You can then either start the backend using your IDE by running the `main` method in the `Application.kt` file, or start
+Now, either start the backend using your IDE by running the `main` method in the `Application.kt` file, or start
 the Spring Boot server using `./mvnw spring-boot:run`. You should be able to access your GraphQL dashboard
 at: `http://localhost:8080/graphiql`.
 
 To start the frontend, make sure your artifacts are installed using `npm install` and run `npm run dev`.
 
+If you now visit `localhost:3000/posts`, you should be able to see the posts.
+
+Next, add `<CommentList postId={postId as string} />` and `<CommentForm postId={postId as string} />` to
+the `/blog-web/src/pages/posts/[postId]/index.tsx` page, right
+before the `</DefaultLayout>`. Make sure you import both of them.
+
+You should now be able to create, list, edit and view posts and comment on them. We leave it up to you to turn the rest
+of the blog into an absolute gem!
+
 ## Tips
 
 - If you want to *update* an existing scaffolding, make start with an empty commit. This way, you can easily see