ENDOC-433 First pass at reformatting #441

Lyd1aCla1r3 · 2022-02-28T21:59:07Z

No description provided.

jyunmitch

sorry ahead of time, lots of comments on this one, probably from previous experience with with it

jyunmitch · 2022-03-01T14:24:26Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

 ``` sh
 ent check-env develop
 ```  

 ### Manual Setup
-The `ent jhipster` command is the recommended way to generate microservices and micro frontends but you can also setup JHipster and the Entando Blueprint yourself. You should then use the `jhipster` command instead of `ent jhipster` for the tutorial.   
+We recommend using the `ent jhipster` command to generate microservices and micro frontends, but you can also run the following commands to initialize JHipster and the Entando Blueprint. If you choose the manual setup, replace all instances of `ent jhipster` in this tutorial with the `jhipster` command.


I am very confused. If these are the manual steps, why didn't all the commands come with jhipster instead of ent jhipster so I don't have to replace them?

so the manual steps header is ### and under prereqs; the prerequisite for not using the cli is to fire off the commands that follow, which are the jhipster and ent installs. if you go the manual route then any "ent jhipster" you encounter when you get to the actual tutorial should be replaced with "jhipster"

I think the instructions were always confusing and I never knew which are the manual steps.

I think the issue is that the reference point keeps changing...the header says manual setup>> first sentence starts with recommended, so that must be the manual setup. But second part of that sentence says you can also do something else, is that the alternative or the manual steps? Because of the structure of these sentences, it is rather confusing, especially at this point when there could be several ways of doing things and one doesn't know that.

hm. i think the best remediation is to be very explicit to clear up any confusion. i'll make the language more explicit.

jyunmitch · 2022-03-01T14:30:11Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

@@ -38,76 +39,85 @@ npm install -g [email protected]
 ```

 ## Generate the Project
+Whether you elect to use the `ent jhipster` command or perform a manual setup, the next step is to create a project with microservices.


I am still thinking this is part of the manual setup and am still confused if I am following the manual setup or not. I can't go further because I can't figure out if I am supposed to change ent jhipster to just jhipster or not.

no... manual setup was a ### header below prereqs. generate the project is the start of the tutorial. you can go further! the disclaimer indicates that - whether or not you chose to use the cli this is the next step

I think if the manual setup paragraph was clearer, this would be fine.

jyunmitch · 2022-03-01T14:34:22Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

-     - `Would you like to install other generators from the JHipster Marketplace?` (No)
-
- 4. Next, add an Entity to your microservice and create the corresponding Micro Frontends. For the tutorial, `Conference` is the name of the entity that will be added to the application.
+3. You'll be presented with a series of prompts to configure your project. These are listed below, with the base values for this tutorial in parentheses. Except where noted in **bold**, you can input what works best for you. Note that hitting "Enter" will select the default option.


I think the last sentence deserves being in bold, because it is an important point and I remember thinking that was useful when I went through this several times.

'base values' >> is default values more clear?

no, base values are the values selected for this tutorial. they are not always the default values.

i actually think it's kind of awkward to bold that... that's like you're recommending to use the default, which is not necessarily the case. and if you just hit enter without thinking then you don't input required information in some cases

Got it! Not a big deal. I guess I was thinking it eases the process

jyunmitch · 2022-03-01T14:38:36Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

+    - `As you are running in a microservice architecture, on which port would like your server to run? It should be unique to avoid port conflicts.` (8081)
+    - `What is your default Java package name?` (Up to you)
+    - `Which *type* of database would you like to use?` (SQL)
+          - If no database is selected you'll be building a stateless microservice, which is a valid choice, but the rest of this tutorial won't work.


If no database is selected, you'll be building a stateless microservice which is a valid choice, but the rest of this tutorial won't work. >> moved comma, which reads better, I think.

i think there needs to be a comma between microservice and which; "which is a valid choice" is an aside

jyunmitch · 2022-03-01T14:42:41Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

+    - `Would you like to use Maven or Gradle for building the backend?` (**Maven**) <-- this is required for Entando
+    - `Which other technologies would you like to use?` (**Don't select any other technologies**)
+    - `What name would you give to the bundle to share on an Entando digital-exchange?` (Up to you)
+    - `Which is the organization name to use when publishing the docker image?` (**Enter the name of the organization where you are going to push your Docker image. If you're using your personal Docker hub account enter your username.**) <-- this can be changed later as needed


should this start with 'What organization'? I read this a couple of times because I kept thinking there was a list of choices that I was supposed to know about or had preentered

yeah i totally left the text in all the questions untouched, because this is what you actually get when you run the code. it should be tweaked in many cases...

jyunmitch · 2022-03-01T14:59:31Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

+    - `Do you want to generate micro frontends?` (Up to you)
+
+- At this point the blueprint will generate controllers, repositories, services, and micro frontends for your entity.  
+    - `Overwrite src/main/resources/config/liquibase/master.xml?` When prompted with a conflict at this stage, enter `a` for "All." This will override existing files with the configuration changes needed for your new entity.


I always wanted this point to be bolded because I did not notice this until going through this tutorial a couple of times or more. My bad but I can't be the only one who glosses over steps that are not totally required.:)

lol we must punish them for the oversight! jk - i had already started approving overwrites before i read this, too :P i'll draw attention

jyunmitch · 2022-03-01T15:12:16Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

-   * ```/bundle``` is used to assemble the project code into an Entando bundle.
+   * ```/src/main/docker``` contains Docker files to help with local development environments.
+   * ```/src/main/java``` and ```src/main/resources``` contain the microservice codebase and configuration.
+   * ```/ui``` holds the React-based micro frontends. By default, each entity is allocated an MFE for details, form, and table.


Is there one MFE or multiple? It also sounds like there could be multiple entities in this tutorial, is that right? Doesn't it get generated? >>"by default, an MFE is generated for each entity to display details, form, and table."

i have the same question. i left the language as is because it could go either way, but i was also wondering... @nshaw i feel like we're talking about 3 MFEs here

jyunmitch · 2022-03-01T15:15:25Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

+   * ```/src/main/docker``` contains Docker files to help with local development environments.
+   * ```/src/main/java``` and ```src/main/resources``` contain the microservice codebase and configuration.
+   * ```/ui``` holds the React-based micro frontends. By default, each entity is allocated an MFE for details, form, and table.
+   * ```/bundle``` is used to assemble the project code into an Entando Bundle.

 ## Next Steps
 You now have a choice:


this reads kind of fatalistic? Maybe 'Congratulations on ... then now you can choose between these ...'

LOL it's the matrix all over again. i didn't care enough to change it? but yeah i'll rephrase to make it seem a little less dire

jyunmitch · 2022-03-01T15:20:58Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

-   - [Learn about the key elements included in the Blueprint generated widgets](../../../docs/create/blueprint-features.md)
-   - [Iterate on your data model using the JHipster Domain Language (JDL)](./update-data-model.md)
+
+- [Build your Entando Bundle](../pb/publish-project-bundle.md) and deploy your microservice and micro frontends to the Entando Component Repository


How about "Build and Deploy your Entando bundle to the Entando ..." because this makes it sound like deploying it will be a separate step. Another confusing thing is that a bundle is not really a bundle since the MS and MFE are deployed separately.

@jyunmitch "a bundle is not really a bundle"?? please rephrase?

After you brought this up and Nathan clarified it, it all makes sense. But if it is a bundle, they should stay together when deployed but sadly they don't. Nothing is wrong about the verbiage. I just noticed it always says it this way, 'deploy your mfe and ms...' and in thinking about it, it makes sense.

jyunmitch · 2022-03-01T15:24:53Z

vuepress/docs/v6.3.2/tutorials/create/ms/generate-microservices-and-micro-frontends.md

-   - [Iterate on your data model using the JHipster Domain Language (JDL)](./update-data-model.md)
+
+- [Build your Entando Bundle](../pb/publish-project-bundle.md) and deploy your microservice and micro frontends to the Entando Component Repository
+- Folow the [Running Locally tutorial](./run-local.md) to run your microservice and micro frontends in your local dev environment


the title for the page is now 'Run Blueprint-generated Microservices and Micro Frontends in Dev Mode' >> this is too long but the link reference should somewhat match?

agreed - i will be totally honest; i did not check this link! i'll go through the others, too

nshaw · 2022-03-02T22:57:16Z

@Lyd1aCla1r3 you have two approvals but I saw a new comment from you. Will leave this one to you to merge when you're ready or to tag us for one more review.

ENDOC-433 First pass at reformatting

628c01a

Lyd1aCla1r3 requested review from nshaw and jyunmitch February 28, 2022 21:59

ENDOC-433 Fix capitalization error

9120ce2

nshaw approved these changes Mar 1, 2022

View reviewed changes

jyunmitch reviewed Mar 1, 2022

View reviewed changes

Lydia added 2 commits March 1, 2022 12:31

ENDOC-433 Minor fixes

b780bba

ENDOC-433 Apply overlooked review comment

d604f1e

jyunmitch approved these changes Mar 2, 2022

View reviewed changes

ENDOC-433 Explicit language :)

7cb8790

nshaw approved these changes Mar 3, 2022

View reviewed changes

nshaw merged commit 465e5ae into main Mar 3, 2022

nshaw deleted the ENDOC-433 branch March 3, 2022 18:55

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-433 First pass at reformatting #441

ENDOC-433 First pass at reformatting #441

Lyd1aCla1r3 commented Feb 28, 2022

jyunmitch left a comment

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 2, 2022

Lyd1aCla1r3 Mar 2, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 2, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 2, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

jyunmitch Mar 2, 2022

jyunmitch Mar 1, 2022

Lyd1aCla1r3 Mar 1, 2022

nshaw commented Mar 2, 2022

ENDOC-433 First pass at reformatting #441

ENDOC-433 First pass at reformatting #441

Conversation

Lyd1aCla1r3 commented Feb 28, 2022

jyunmitch left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

nshaw commented Mar 2, 2022