Update README.md with link project board and issues

CONTRIBUTING.md

@@ -1,30 +1,117 @@
-# Contributing to Jakarta EE Platform
+# Contributing to Jakarta EE Documentation
 
 Thanks for your interest in this project.
 
 ## Project description
 
-The Jakarta EE Platform project produces the Jakarta EE
-platform specification, which is an umbrella specification that
-aggregates all other Jakarta EE specifications.
+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.
 
-* [https://projects.eclipse.org/projects/ee4j.jakartaee-platform](https://projects.eclipse.org/projects/ee4j.jakartaee-platform)
+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
 
-* [https://github.com/eclipse-ee4j/jakartaee-platform](https://github.com/eclipse-ee4j/jakartaee-platform)
-* [https://github.com/eclipse-ee4j/jakartaee-tutorial](https://github.com/eclipse-ee4j/jakartaee-tutorial)
-* [https://github.com/eclipse-ee4j/jakartaee-tutorial-examples](https://github.com/eclipse-ee4j/jakartaee-tutorial-examples)
-* [https://github.com/eclipse-ee4j/jakartaee-firstcup](https://github.com/eclipse-ee4j/jakartaee-firstcup)
-* [https://github.com/eclipse-ee4j/jakartaee-firstcup-examples](https://github.com/eclipse-ee4j/jakartaee-firstcup-examples)
-* [https://github.com/eclipse-ee4j/jakartaee-schemas](https://github.com/eclipse-ee4j/jakartaee-schemas)
+* [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
+
+##### Normal Branches
+
+* Restrict work on a single feature or issue to a single branch
+* Branch name: `feature/[issue #]_description_if_necessary`
+  * Example: `feature/123_this_is_an_example`
+  * Example: `feature/123`
+  * Example: `feature/remove_stale_files (no issue number)`
+
+##### Release Branches
+
+* For the main tutorial repo and any other repos with Antora content (that does not include a playbook), we’ll keep a release branch so that we maintain docs for the particular version of Jakarta EE.
+* The main branch will represent the current release. All previous releases should have their own branch.
+Branch name: `release/[version]`
+  * Example: `release/9.1`
+  * Example: `release/10`
+
+##### Commits
+
+* Include the issue # in the message (if applicable)
+  * Example: “#123 Adds a the ability to synchronize with the example repo”
+  * Example: “Updates #123 with changes for pom file”
+  * Example: “Removed stale files”
+
+### Creating diagrams
+
+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 three formats:
+
+- `*.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)
+    - If there's no 'Open Sans' option, pick 'Custom'.
+      ![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)
+    - Type text and verify that the font is Open Sans
+      ![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 (you can use opacity to affect the depth of the color).
+    - Primary colors:
+        - Blue: `#1B208B`
+        - Orange: `#F98200`
+        - Black: `#3D3D3D`
+        - White: `#FFFFFF`
+    - Secondary colors:
+        - Yellow: `#FDB940`
+        - Grey: `#58595B`
+        - Dark blue: `#131660`
+
+- Arrows must be Orange (`#F98200`)
+
+- Background must be white (`#FFFFFF`) 
+
+### Terminology
+
+| Old | New |
+| --- | --- |
+| Jakarta Foo Technology | Jakarta Foo API |
+| JavaBeans components | beans |
+| application server | Jakarta runtime |
+| (web) container | servlet container | 
+| context root | context path |
+| web context | application scope |
+
+* 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
 
@@ -44,6 +131,5 @@ For more information, please see the Eclipse Committer Handbook:
 
 ## Contact
 
-Contact the project developers via the project's "dev" list.
-
-* [https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev](https://accounts.eclipse.org/mailing-list/jakartaee-platform-dev)
+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.

README.md

@@ -1,81 +1,50 @@
 # Jakarta EE Tutorial
 
-![ build](https://github.com/eclipse-ee4j/jakartaee-tutorial/workflows/build/badge.svg)
-
 This repository contains the source files that are used to build the
-_Jakarta Enterprise Edition (Jakarta EE) Tutorial_. The source files
-are authored in [AsciiDoc](http://asciidoc.org/).  AsciiDoc is similar
-to markdown but is particularly suited for user documentation.  
-
-Note that the Jakarta EE Tutorial code examples are located in a
-separate repository
-[eclipse-ee4j/jakartaee-tutorial-examples](https://github.com/eclipse-ee4j/jakartaee-tutorial-examples).
-
-## Contributing
-The easiest way to contribute is by opening an issue in this project
-that contains feedback and review comments.
-
-The Jakarta EE Tutorial project is also open for contributions and your
-help is greatly appreciated. If you have an idea for the tutorial and
-want to add a section or update an existing section, then review the
-following links:
-
-* [Contribute](CONTRIBUTING.md)
-* [Pull Request Acceptance Workflow](src/main/jbake/assets/pr_doc_workflow.md)
-* [License](LICENSE.md)
-
-## Building the Jakarta EE Tutorial
+_Jakarta Enterprise Edition (Jakarta EE) Tutorial_. 
+The source files are authored in [AsciiDoc](https://asciidoc.org/). 
+AsciiDoc is similar to markdown but is particularly suited for user documentation. 
+The source files are processed and integrated into the Jakarta EE Documentation site using
+[Antora](https://antora.org/), 
+which is a tool for building documentation sites.
 
-The following directions explain how to do local builds of the
-tutorial. Note that any changes that are pushed to the master branch
-automatically trigger a build of the site files and tutorial sources.
-The results are automatically pushed to the gh-pages branch. You can
-view the published site
-[here](https://eclipse-ee4j.github.io/jakartaee-tutorial).
+You can always find the most recent build of the Jakarta EE Documentation site here:
+https://jakartaee.github.io/jakartaee-documentation/.
 
-### Pre-Requisites
+## A Note about Images
 
-- Maven
-- JDK8+
+We keep the source files (VSD) and the published format (SVG)
+for images in the `src/main/antora/modules/common/images` folder. 
+However, currently all the source file names don't match their corresponding SVG file. 
+If you modify a source image, 
+please help us out and rename it to match the output image.
 
-Note that manually deploying the site requires password-less
-authentication. This is done by exporting your SSH public key into your
-GitHub account.
+Guidelines for generating new images can be found in the [Contributing guide](CONTRIBUTING.md). 
 
-### Build the Site Locally
+## Building
 
-The site is generated under `target/staging`. Open
-`file:///PATH_TO_PROJECT_DIR/target/staging` in a browser to view the
-output.
+The contents of this repo are built by
+the [jakartaee-tutorial-playbook repository](https://github.com/jakartaee/jakartaee-documentation).
+See that repo for details.
 
-```
-mvn generate-resources
-```
+## Related Repositories
 
+* [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.
 
-### Deploy the Site to Github Pages
-
-If you want to manually push a build to the gh-pages branch, use:
-
-```
-mvn deploy -Ppublish-site
-```
-Never commit changes to the *gh-pages* branch directly.
-
-### Produce a Zip File for Download
-
-To produce a zip file containing the generated HTML files, use:
-
-```
-mvn package
-```
+## Contributing
 
-When making a release on GitHub, this zip file should be added to the release.
+This project is open for contributions, and your
+help is greatly appreciated. 
+The easiest way to contribute is by opening an [issue](https://github.com/jakartaee/jakartaee-tutorial/issues) in this project
+that contains feedback and review comments. 
 
-## Links
+You can also create PRs directly while viewing the published documentation by using the Edit button in the UI.
 
-- [Asciidoctor Maven Plugin](https://asciidoctor.org/docs/asciidoctor-maven-plugin/)
+If you want to keep up with our project planning across all of the repos, see the [project board](https://github.com/orgs/jakartaee/projects/7).
 
-- [AsciiDoc User Guide](http://asciidoc.org/userguide.html)
+If you'd like to propose changes or additions to the content and/or images,
+please read the [Style guide](STYLE_GUIDE.adoc) and  
+[Contributing guide](CONTRIBUTING.md) for more information.
 
-- [Asciidoctor quick reference](http://asciidoctor.org/docs/asciidoc-syntax-quick-reference)