Improve documentation

[nicolas63]

Overview of the feature request

Today, all our documentation is in the readme and it is too voluminous. It's time to create a real documentation ( With read the docs )

I have already added this repository on read the docs and juste copy paste the readme (https://jhipsternet.readthedocs.io/en/latest/)

Related issues or PR

• [x] Checking this box is mandatory (this is just to show you read everything)

[nicolas63]

https://docs.readthedocs.io/en/stable/intro/getting-started-with-sphinx.html

[ivanmonteiro]

I have a few suggestions for the documentation. The first one is:

• Add a "catchy" headline to grab attention

Add a headline to Github's readme (https://github.com/jhipster/jhipster-dotnetcore/blob/main/README.md) and ReadTheDocs. A headline changes the way people read the rest of the docs and the way they remember the project. The headline frames the rest of the experience. Ideally, It should be short and grab the attention of the reader.

I have written a few headlines:

Generate a Full Stack .Net application with entities, relationships, Angular/React/Blazor frontend and more

Quickly generate a .Net backend and choose Angular, React or Blazor for the frontend with entities, relationships, repository, services and more

Quickly generate a .Net application with entities, relationships, repository, services, Angular/React/Blazor frontend and more

Suggestions are welcome from other developers and community. It does not have to be perfect the first time (and most likely will not be perfect the first time). @nicolas63 @maznag please comment if you have a headline suggestion, don't be shy!

[ivanmonteiro]

The second suggestion for improving the documentation is to:

• add an introductory gif or video to grab attention of new visitors

I'm thinking about a simple video/gif at the top of the readme (below the the headline) showing simple steps like:

• adding entitiy
• running the generated application

Thinking about the experience of first-time visitors of the repository, seeing gif or video preview of the project's capabilities will most likely catch such visitor's attention and (hopefully) the visitor will try the project. New visitors might not be familiar with JHipster and just landed at the repository from a google search (as example).

It can be a gif. The pros of using a gif is the autoplay feature. The con is size, so the gif should be short.

Or it can be a youtube video, but it will not autoplay and it can have a longer duration. The downside of no autoplay is that only a percentage of new visitors will click the play button.

Creating and editing the gif or video will most likely take some time and need some adjustments.

As always, suggestions are welcome! Let me know what you think.

[nicolas63]

@ivanmonteiro totally agree with you I think we absolutely have to improve this part. I think we need to improve the generated readme with usefull command and all informations useful for the developers. Maybe add a complete guide like https://github.com/jhipster/jhipster-guides/tree/main/guides For gif vs videos i think gif are easier to realize

[nicolas63]

Maybe we can create a Projects in github to trace and distribute the realisation of the doc

[ivanmonteiro]

Maybe we can create a Projects in github to trace and distribute the realisation of the doc

Good idea. Could you setup the project?

[nicolas63]

https://github.com/jhipster/jhipster-dotnetcore/projects/1