Feature/#78 refresh intro and preface

CONTRIBUTING.md

@@ -1,26 +1,21 @@
-# Contributing to Jakarta EE Platform
+# Contributing to Jakarta EE Documentation
 
 Thanks for your interest in this project.
 
 ## Project description
 
 The Eclipse Documentation for Jakarta EE project hosts documentation intended for programmers interested in developing and deploying Jakarta EE applications. It covers the technologies comprising the Jakarta EE platform and describes how to develop applications using Jakarta EE components and deploy them on Jakarta EE runtimes.
 
-Link TBD
+Eclipse project page: https://projects.eclipse.org/projects/ee4j.jakartaee-documentation
 
 ## Developer resources
 
-Information regarding source code management, builds, coding standards, and
-more.
-
-* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer](https://projects.eclipse.org/projects/ee4j.jakartaee-platform/developer)
-
 The project maintains the following source code repositories
 
-* [jakartaee-tutorial-playbook](https://github.com/virtua-tech/jakartaee-tutorial-playbook)
-* [jakartaee-tutorial](https://github.com/virtua-tech/jakartaee-tutorial)
-* [jakartaee-tutorial-ui](https://github.com/virtua-tech/jakartaee-tutorial-ui)
-
+* [eclipse-ee4j/jakartaee-examples](https://github.com/eclipse-ee4j/jakartaee-examples) - Contains examples used in the tutorial (and additional examples)
+* [jakartaee/jakartaee-documentation](https://github.com/jakartaee/jakartaee-documentation) - builds documentation site
+* [jakartaee/jakartaee-documentation-ui](https://github.com/jakartaee/jakartaee-documentation-ui) - HTML and CSS assets used for the documentation site look and feel.
+* 
 ### Coding guidelines
 
 #### Branches
@@ -50,38 +45,42 @@ Branch name: `release/[version]`
 
 ### Creating diagrams
 
-Diagrams are located in `src/main/asciidoc/images`.
+Diagrams are located in `src/main/antora/modules/common/images` or in the `images` folder of the module;
+for example `src/main/antora/modules/cdi/images`.
 Use [draw.io](https://draw.io) to create/adjust diagrams.
 This tool is primarily chosen for being free to use and the most flexible.
-For portability and maintainability, make sure that the diagram is saved/exported into following 3 formats:
+For portability and maintainability, make sure that the diagram is saved/exported into following three formats:
 
-- `*.drawio`
-- `*.vsdx`
-- `*.svg`
+- `*.drawio` (use the Save function)
+- `*.vsdx` (use the Export function)
+- Editable `*.svg` (use the Save As function) 
 
 The `*.drawio` format ensures being able to reopen exactly the intended diagram in the original tool.
 The `*.vsdx` format ensures being able to import the diagram in another tool as this is the most supported format by
 various diagramming tools, just in case that draw.io stops to exist in some unpredictable future.
 The `*.svg` format is ultimately used to embed the diagram in the tutorial document.
 
+Also, make sure you use a hyphen ("-") in the name as a delimiter; for example `persistance-mapping`.
+
 #### Diagram requirements
 
 - Font must be 'Open Sans' conform
   the [Jakarta EE Brand Usage Handbook](https://jakarta.ee/legal/trademark_guidelines/jakarta-ee-branding-guidelines.pdf).
   You can use Google Fonts for this.
   In case you're using draw.io:
     - Wherever you see a 'Font' dropdown, unfold it.
-      ![Select font](README/images/drawio-font-1-select-font.png)
+      ![Select font](readme-images/drawio-font-1-select-font.png)
     - If there's no 'Open Sans' option, pick 'Custom'.
-      ![Select custom](README/images/drawio-font-2-select-custom.png)
+      ![Select custom](readme-images/drawio-font-2-select-custom.png)
     - Choose the 'Google Fonts' option and set the font name to 'Open Sans' and apply.
-      ![Set Google Open Sans](README/images/drawio-font-3-set-google-open-sans.png)
+      ![Set Google Open Sans](readme-images/drawio-font-3-set-google-open-sans.png)
     - Type text and verify that the font is Open Sans
-      ![Using Google Open Sans](README/images/drawio-font-4-using-google-open-sans.png)
+      ![Using Google Open Sans](readme-images/drawio-font-4-using-google-open-sans.png)
+- Font size for all text should be 12pt 
 
 - Color must be one of those defined
   in [Jakarta EE Brand Usage Handbook](https://jakarta.ee/legal/trademark_guidelines/jakarta-ee-branding-guidelines.pdf),
-  along with black and white.
+  along with black and white (you can use opacity to affect the depth of the color).
     - Primary colors:
         - Blue: `#1B208B`
         - Orange: `#F98200`
@@ -92,6 +91,10 @@ The `*.svg` format is ultimately used to embed the diagram in the tutorial docum
         - Grey: `#58595B`
         - Dark blue: `#131660`
 
+- Arrows must be Orange (`#F98200`)
+
+- Background must be white (`#FFFFFF`) 
+
 ### Terminology
 
 | Old | New |
@@ -106,6 +109,10 @@ The `*.svg` format is ultimately used to embed the diagram in the tutorial docum
 * Do not use in-house abbreviations! E.g. do not use “DD” but write out fully “deployment descriptor”.
 * List items should always start with capital and end with full stop.
 
+## Style guide
+
+If you're going to write documentation, please make sure you follow the [style guide](STYLE_GUIDE.adoc).
+
 ## Eclipse Contributor Agreement
 
 Before your contribution can be accepted by the project team contributors must
@@ -124,6 +131,5 @@ For more information, please see the Eclipse Committer Handbook:
 
 ## Contact
 
-Contact the project developers via the project's "dev" list.
-
-* [TBD]
+Contact the project developers via the project's "dev" list:
+https://accounts.eclipse.org/mailing-list/jakartaee-documentation-dev or via the Github issue tracker.

STYLE_GUIDE.adoc

@@ -107,3 +107,6 @@ For details, see https://sembr.org/[Semantic Line Breaks].
 In short, don't use them etc., e.g., and i.e.
 See https://www.eclipse.org/org/documents/writing-style-guide/#31[Latinisms].
 
+== Conventions
+
+Please follow the https://jakartaee.github.io/jakartaee-documentation/jakartaee-tutorial/current/index.html#_conventions[conventions described in the tutorial].

src/main/antora/modules/ROOT/nav.adoc

@@ -1,7 +1,7 @@
 
-.Introduction
+xref:index.adoc[]
 
-* xref:index.adoc[]
+.Introduction
 
 * xref:intro:overview/overview.adoc[]
 

src/main/antora/modules/ROOT/pages/index.adoc

@@ -1,50 +1,47 @@
 [preface]
-= Preface
-
-This tutorial is a guide to developing enterprise applications for the Jakarta EE 9 Platform, using Eclipse GlassFish Server.
-
-Eclipse GlassFish Server is the leading open-source and open-community platform for building and deploying next-generation applications and services.
-Eclipse GlassFish Server, developed by the Eclipse GlassFish project open-source community at https://projects.eclipse.org/projects/ee4j.glassfish[^], is a compatible implementation of the Jakarta EE 9 platform specification.
-This lightweight, flexible, and open-source application server enables organizations not only to leverage the new capabilities introduced within the Jakarta EE 9 specification, but also to add to their existing capabilities through a faster and more streamlined development and deployment cycle.
-Eclipse GlassFish Server is hereafter referred to as GlassFish Server.
 
-== Audience
+= Preface
 
-This tutorial is intended for programmers interested in developing and deploying Jakarta EE 9 applications.
-It covers the technologies comprising the Jakarta EE platform and describes how to develop Jakarta EE components and deploy them on the Eclipse GlassFish.
+include::ROOT:partial$draft.adoc[]
 
-== Before You Read This Book
+== Legal
 
-Before proceeding with this tutorial, you should have a good knowledge of the Java programming language.
-A good way to get to that point is to work through the Java(TM) Tutorials https://dev.java/learn/it [^].
+This documentation and the accompanying materials are made available under the terms of the Eclipse Public License v. 2.0,
+which is available at https://www.eclipse.org/legal/epl-2.0.
 
-== Related Documentation
+SPDX-License-Identifier: EPL-2.0
 
-The GlassFish Server documentation set describes deployment planning and system installation.
-To obtain the GlassFish Server documentation, go to https://glassfish.org/docs[^].
+Oracle and Java are registered trademarks of Oracle and/or its affiliates. Other names may be trademarks of their respective owners.
 
-The Jakarta EE 9 API specification can be viewed at https://jakarta.ee/specifications/platform/9/[^].
+== About this Tutorial
 
-Additionally, the Jakarta EE Specifications at https://jakarta.ee/specifications[^] might be useful.
+This tutorial explains how to use the features of the Jakarta EE Platform to build cloud-native applications,
+such as microservices, "right sized" services, and server-based web applications.
 
-For information about creating enterprise applications in the NetBeans Integrated Development Environment (IDE), see https://netbeans.apache.org/kb/[^].
+== Prerequisites
 
-For information about Apache Derby for use with GlassFish Server, see https://db.apache.org/derby/docs/10.14/adminguide/[^].
+Jakarta EE applications use the Java Platform, and are usually written in the Java programming language.
+All the examples in this tutorial are written in Java.
+If you're new to Java, spend some time getting up to speed on the language and platform;
+a good place to start is https://dev.java/learn/[dev.java/learn].
 
-The GlassFish Samples project is a collection of sample applications that demonstrate a broad range of Jakarta EE technologies.
-The GlassFish Samples are available from the GlassFish Samples project page at https://github.com/eclipse-ee4j/glassfish-samples/[^].
+Each topic in this tutorial provides some background information,
+but in general,
+we assume you have a basic understanding of the technologies each Jakarta EE feature works with.
+For example, in the Jakarta Persistence chapter,
+we assume you have a basic understanding of relational databases.
 
 == Conventions
 
-The following table describes the typographic conventions that are used in this book.
+Throughout this tutorial, we use the following typographic conventions:
 
 [width="99%",cols="20%,38%,37%"]
 |===
 |Convention |Meaning |Example
 
-|*Boldface* |Boldface type indicates graphical user interface elements associated with an action or terms defined in text. |From the *File* menu, choose *Open Project*.
+|*Boldface* |Boldface type indicates a term defined in text or graphical user interface elements associated with an action. |A *cache* is a copy stored locally.
 
-A *cache* is a copy that is stored locally.
+From the *File* menu, choose *Open Project*.
 
 |`Monospace` |Monospace type indicates the names of files and directories, commands within a paragraph, URLs, code in examples, text that appears on the screen, or text that you enter. |Edit your `.login` file.
 
@@ -61,26 +58,28 @@ The command to remove a file is `rm _filename_`.
 
 == Default Paths and File Names
 
+include::ROOT:partial$not_updated.adoc[]
+
 The following table describes the default paths and file names that are
 used in this book.
 
 [width="99%",cols="20%,38%,38%"]
 |===
 |Placeholder |Description |Default Value
 
-|`_as-install_` |Represents the base installation directory for GlassFish Server. | Installations on the Solaris operating system, Linux operating system, and Mac operating system:
+|`_as-install_` |Represents the base installation directory for GlassFish Server. | Installations on the Linux, UNIX, or macOS:
 
 `_user's-home-directory_/glassfish6/glassfish`
 
 Windows, all installations:
 
 `_SystemDrive_:\glassfish6\glassfish`
 
-|`_as-install-parent_` |Represents the parent of the base installation directory for GlassFish Server. |Installations on the Solaris operating system, Linux operating system, and Mac operating system:
+|`_as-install-parent_` |Represents the parent of the base installation directory for GlassFish Server. |Installations on UNIX/Linux/macOS:
 
 `_user's-home-directory_/glassfish6`
 
-Windows, all installations:
+Windows:
 
 `_SystemDrive_:\glassfish6`
 

src/main/antora/modules/ROOT/partials/draft.adoc

@@ -0,0 +1,4 @@
+[NOTE]
+====
+This section is currently a draft, and is subject to change.
+====