ENDOC-330 reorganization of intro pages content #507

jyunmitch · 2022-05-04T13:52:27Z

will fix the links in the next round. it's from moving the development concepts content to a different location.

vuepress/docs/v7.0/docs/getting-started/concepts-overview.md

jyunmitch · 2022-05-04T14:00:38Z

vuepress/docs/v7.0/docs/getting-started/README.md


 1. [Install Kubernetes](#install-kubernetes)
 2. [Prepare the Kubernetes Environment](#prepare-kubernetes)
 3. [Deploy Entando](#deploy-entando)

-
-We've tested a variety of Kubernetes implementations, including Minikube, Minishift, CodeReady Containers, K3s, and Microk8s, to find the optimal combination of low CPU/memory usage, fast startup times, and minimal configuration. After downloading the necessary files, we'll have our own instance of Kubernetes up and running in <60 seconds.


@nshaw, Not sure if removing this was a good idea, just thinking that a tutorial should keep peripheral information to a minimum.

@jyunmitch i had the same thoughts here; i thought i'd changed it to read "we selected k3s to use the optimal combination..."
i don't think we need to dive into process and trial and error, just discuss what's topical and pertinent

@jyunmitch looks good to me.

vuepress/docs/v7.0/docs/README.md

Lyd1aCla1r3 · 2022-05-04T19:31:56Z

vuepress/docs/v7.0/docs/getting-started/README.md

@@ -41,21 +29,20 @@ https://multipass.run/#install
 curl -sfL https://get.entando.org | bash
 ```

-3. The progress of the install will be displayed on the console. Installation can take 10+ minutes depending on how long the Docker images take to download. The sequence of steps performed by the CLI is identical to the manual steps below. To understand what the CLI does, review the manual steps.
+3. The progress of the install will be displayed on the console. Installation can take up to 10 minutes, depending on how long the Docker images take to download. The sequence of steps performed by the CLI is identical to the manual steps below. To understand what the CLI does, review the manual steps.


will be displayed -> is displayed

10+ means more than ten

time has been reduced

Lyd1aCla1r3 · 2022-05-04T19:33:50Z

vuepress/docs/v7.0/docs/getting-started/README.md

 4. The URL to access the Entando App Builder will print to the console once the install completes.
 5. Login with username:`admin` and password: `adminadmin`. Refer to [Login to Entando](#login-to-entando) for more information and next steps.

 ## Manual Install

-Manual installation allows you to configure a shared cluster or customize a local developer environment. The following learn-as-you-go approach gives you a working knowledge of Kubernetes as you get Entando up and running in a local environment. This is a three stage process:
+Manual installation allows you to configure a shared cluster or customize a local developer environment. The following learn-as-you-go approach gives you a working knowledge of Kubernetes as you get Entando up and running in a local environment. After downloading the necessary files, your instance of Kubernetes will be up and running in <60 seconds.


gives you a -> provides

too many "up and running"s here

<60 seconds is the guaranteed time frame based on empirical data?

Lyd1aCla1r3 · 2022-05-04T19:34:47Z

vuepress/docs/v7.0/tutorials/README.md


-Entando supports full stack micro frontend and microservice architectures for codebases that are easier to understand, maintain, and debug across large, distributed teams, and comes with a private component repository that makes it easy for teams to share and reuse components.
+* Build end-to-end modularity into your application for codebases that are easier to maintain & debug.


I think this was missed. I still see the &.

Lyd1aCla1r3 · 2022-05-04T19:35:59Z

vuepress/docs/v7.0/tutorials/README.md


-Use the navigation on the left to find step-by-step tutorials for common tasks or check out our learning paths below for a more structured approach.
+Check out the learning paths below to start, with varying levels of experience and needs for the developer.


"to start" is awkward, like to start what?

nshaw

Few requests and then apply to next as well.

nshaw · 2022-05-10T20:02:01Z

vuepress/docs/v7.0/docs/getting-started/README.md


 1. [Install Kubernetes](#install-kubernetes)
 2. [Prepare the Kubernetes Environment](#prepare-kubernetes)
 3. [Deploy Entando](#deploy-entando)

-
-We've tested a variety of Kubernetes implementations, including Minikube, Minishift, CodeReady Containers, K3s, and Microk8s, to find the optimal combination of low CPU/memory usage, fast startup times, and minimal configuration. After downloading the necessary files, we'll have our own instance of Kubernetes up and running in <60 seconds.


@jyunmitch looks good to me.

nshaw · 2022-05-10T20:05:16Z

vuepress/docs/v7.0/docs/getting-started/concepts-overview.md

+
+This document explores the architecture of the platform and some notable runtime characteristics.
+
+![entando-architecture](../entando-architecture.png)


This looks like a screenshot of the full slide from the presentation with left and right background images. I think we had that before but can we clean that up and just include the diagram itself? We can probably drop the header as well but then when you click on the image you just get the interesting parts.

nshaw · 2022-05-10T20:06:59Z

vuepress/docs/v7.0/docs/getting-started/concepts-overview.md


 #### Entando Kubernetes Service

-The Entando Kubernetes Service is part of the Entando cluster
+The Entando K8s service is part of the cluster


Minor, but maybe Kubernetes integration service per the glossary. I wouldn't shorten it here in the full name like this.

vuepress/docs/v7.0/docs/getting-started/concepts-overview.md

nshaw · 2022-05-10T20:11:10Z

vuepress/docs/v7.0/docs/getting-started/concepts-overview.md


 #### Using the Openshift Dashboard

-On the Openshift dashboard, ingresses are not exposed directly as pods and deployments. The dashboard provides direct access to the Ingress Routes (or simply routes) under the `Applications` → `Routes` menu.
+On the Openshift dashboard, ingresses are not exposed directly as pods and deployments. The dashboard provides direct access to the ingress routes under the `Applications` → `Routes` menu.


Openshift -> OpenShift

nshaw · 2022-05-10T20:12:11Z

vuepress/docs/v7.0/tutorials/README.md


-Entando supports full stack micro frontend and microservice architectures for codebases that are easier to understand, maintain, and debug across large, distributed teams, and comes with a private component repository that makes it easy for teams to share and reuse components.
+* Build end-to-end modularity into your application for codebases that are easier to maintain & debug.


I think this was missed. I still see the &.

nshaw · 2022-05-16T20:42:49Z

vuepress/docs/next/tutorials/README.md

 # Learning Paths

-::: tip Entando simplifies the development of modern apps:
+::: tip Entando simplifies and automates the DevOps lifecycle of applications orchestrated by Kubernetes.


This is a bit too narrow since the 4Cs cover more than just DevOps. Maybe "Entando simplifies the development of composable applications deployed on Kubernetes." I actually don't love these bullets but let's keep those for now.

I took out the blue highlighted box because it always bothered me and we don't use it anywhere else. What about the bullets needs improvement? It feels wrong to publish when something is off on a page that will get the more traffic than most pages.

nshaw · 2022-05-16T20:47:16Z

vuepress/docs/next/tutorials/README.md


-Use the navigation on the left to find step-by-step tutorials for common tasks or check out our learning paths below for a more structured approach.
+Check out the learning paths below, for varying levels of experience and needs for the developer.


I think we discussed improving this - "varying levels of experience and needs" is awkward to me. Maybe "Check out the learning paths below to find step-by-step tutorials for the most common tasks you may encounter."

Lyd1aCla1r3 · 2022-05-17T17:05:43Z

vuepress/docs/next/docs/README.md

@@ -12,28 +12,56 @@ only be available by building from source.

 Entando is the leading open source **Application Composition Platform** for Kubernetes. It enables parallel teams to accelerate development and innovation of business capabilities on a modern, cloud-native, and Kubernetes-native stack.

-With native support for Javascript app development, a micro frontend and microservices architecture, deployment of apps in containers that can be individually scaled up and down, and automated management of containers with Kubernetes, we simplify the move for enterprises looking to modernize across on-prem and cloud infrastructures.
+It is a distributed and composable environment in which components can be built, scaled and iterated independently, helping teams build agile applications that can adapt to change.


would change one instance of "build/built" to "create" to eliminate redundancy

Lyd1aCla1r3 · 2022-05-17T17:06:57Z

vuepress/docs/next/docs/README.md


-![entando-architecture](./entando-architecture.png)
+On the Entando Platform, development of an application is organized into four stages: Create, Curate, Compose, and Consume. In the simplest terms, you create functional building blocks, curate them into a catalog, compose the blocks onto an app or website, which is then consumed by a user.


the second sentence doesn't make sense as-is. simplest option is to add "and" before "compose the blocks." without "and" it's grammatically incorrect.

it's not a grammar rule to use 'and' in a list, it is convention. It is not wrong to leave out 'and' in a list.

Adding 'and' where you suggest breaks up the flow.

I would suggest we follow the 80% rule because most of the suggestions made here may make the content incrementally better, but there's just a lot bigger improvements we can make elsewhere. So unless there is a significant improvement, something is unclear, or just wrong, I would move on and not belabor the point. Some of these issues are just too small to argue about and it's taking up a lot of time. It's ok if we disagree.

belabor is an interesting word choice. the point of this process is to offer both corrections and perspective. ignoring comments that identify valid issues prolongs this cycle and is the biggest contributor to inefficiency.

Lyd1aCla1r3 · 2022-05-17T17:08:01Z

vuepress/docs/next/docs/README.md


-The Entando platform includes the following major elements:
+## Create Components 
+The first step in building a modern application on Entando is to design and create each independent component or functional block. Developers can use the [Entando Component Generator](./create/component-gen-overview.md) and [Blueprint](./create/blueprint-features.md) to automate the building and packaging of project files, with the flexibility to customize while using software they are accustomed to. The modular design of apps built on Entando means new business capabilities can be integrated into your application without reworking existing systems. 


should be consistent with either "they" or "you," not mix these

Lyd1aCla1r3 · 2022-05-17T17:11:17Z

vuepress/docs/next/docs/README.md


-## Why Kubernetes?
+## Curate and Share Components 
+On the Entando Platform, Curate and Share means development teams can bundle and share components within a central catalog. Multiple teams can collaborate on a single component or packaged business capabilities (PBCs) and share them across organizations and applications. They can test and assess components for readiness, manage and publish versions, and share metadata for continuous upgrades. 


"share" is not one of the 4Cs and should not be capitalized in support of Curate

"single component" is redundant and "single" carries over to PCBs on first read, making the plurality seem wrong. should either use "component of PCB" or "components or PCBs," not mix singular and plural.

Share is part of the menu title and need to be consistent with that. Also, the items under that menu header don't really make sense without the Share.

Single is there for emphasis. Can we not belabor this point and sometimes disagree.

Lyd1aCla1r3 · 2022-05-17T17:12:47Z

vuepress/docs/next/docs/README.md

+|  | [Digital Assets](../tutorials/compose/digital-assets-tutorial.md) |
+
+## Consume Applications 
+In the development lifecycle of an application, Consume is the execution stage where users interact with the app. On Entando, the modular design of components and services means they can be scaled individually, or as a whole, according to those interactions. Likewise, content can be updated, engine rules adapted, and upgrades made seamlessly. As a result, the development cycle is a continuous process with minimal disruptions and faster time to market.


"upgrades made seamlessly" is very awkward phrasing

Lyd1aCla1r3 · 2022-05-17T17:15:26Z

vuepress/docs/v7.0/tutorials/README.md

-Entando supports full stack micro frontend and microservice architectures for codebases that are easier to understand, maintain, and debug across large, distributed teams, and comes with a private component repository that makes it easy for teams to share and reuse components.
-
-Use the navigation on the left to find step-by-step tutorials for common tasks or check out our learning paths below for a more structured approach.
+Check out the learning paths below to find step-by-step tutorials for the most common tasks, organized by architecture and levels.


what kind of levels? needs a qualifier. level of complexity? level of stack?

ENDOC-330 reorganization of intro pages content

1763cd9

jyunmitch requested review from nshaw and Lyd1aCla1r3 May 4, 2022 13:52

jyunmitch commented May 4, 2022

View reviewed changes

Lyd1aCla1r3 reviewed May 4, 2022

View reviewed changes

jyunmitch added 5 commits May 5, 2022 09:36

ENDOC-330 review edits

71723b5

ENDOC-330 correct links

461ccb2

ENDOC-330 clear conflict w/ png file

bd1670e

resolve conflict

80f5d2f

ENDOC-330 fix link

e55c56e

nshaw requested changes May 10, 2022

View reviewed changes

jyunmitch added 2 commits May 16, 2022 09:51

Review edits and apply to next

4fbeccb

add missing warning

2a729f0

nshaw requested changes May 16, 2022

View reviewed changes

ENDOC-330 Tutorial intro reworked

b316867

nshaw approved these changes May 17, 2022

View reviewed changes

Lyd1aCla1r3 reviewed May 17, 2022

View reviewed changes

ENDOC-330 final review edits

a51ca8c

nshaw approved these changes May 18, 2022

View reviewed changes

nshaw merged commit 0ce7fe6 into main May 18, 2022

nshaw deleted the ENDOC-330 branch May 18, 2022 16:36

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

ENDOC-330 reorganization of intro pages content #507

ENDOC-330 reorganization of intro pages content #507

jyunmitch commented May 4, 2022 •

edited

Loading

jyunmitch May 4, 2022

Lyd1aCla1r3 May 4, 2022

nshaw May 10, 2022

Lyd1aCla1r3 May 4, 2022

jyunmitch May 5, 2022

Lyd1aCla1r3 May 4, 2022

Lyd1aCla1r3 May 4, 2022

nshaw May 10, 2022

Lyd1aCla1r3 May 4, 2022

nshaw left a comment

nshaw May 10, 2022

nshaw May 10, 2022

nshaw May 10, 2022

nshaw May 10, 2022

nshaw May 10, 2022

nshaw May 16, 2022

jyunmitch May 17, 2022

nshaw May 16, 2022

Lyd1aCla1r3 May 17, 2022

Lyd1aCla1r3 May 17, 2022

jyunmitch May 18, 2022

Lyd1aCla1r3 May 18, 2022

Lyd1aCla1r3 May 17, 2022

Lyd1aCla1r3 May 17, 2022

jyunmitch May 18, 2022

Lyd1aCla1r3 May 17, 2022

Lyd1aCla1r3 May 17, 2022


		Entando supports full stack micro frontend and microservice architectures for codebases that are easier to understand, maintain, and debug across large, distributed teams, and comes with a private component repository that makes it easy for teams to share and reuse components.
		* Build end-to-end modularity into your application for codebases that are easier to maintain & debug.


		Use the navigation on the left to find step-by-step tutorials for common tasks or check out our learning paths below for a more structured approach.
		Check out the learning paths below to start, with varying levels of experience and needs for the developer.


		This document explores the architecture of the platform and some notable runtime characteristics.

		![entando-architecture](../entando-architecture.png)


		Use the navigation on the left to find step-by-step tutorials for common tasks or check out our learning paths below for a more structured approach.
		Check out the learning paths below, for varying levels of experience and needs for the developer.


		![entando-architecture](./entando-architecture.png)
		On the Entando Platform, development of an application is organized into four stages: Create, Curate, Compose, and Consume. In the simplest terms, you create functional building blocks, curate them into a catalog, compose the blocks onto an app or website, which is then consumed by a user.

ENDOC-330 reorganization of intro pages content #507

ENDOC-330 reorganization of intro pages content #507

Conversation

jyunmitch commented May 4, 2022 • edited Loading

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 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

jyunmitch commented May 4, 2022 •

edited

Loading