CONTRIBUTING.adoc

Contributing to the Eclipse Che documentation

Table of Contents

• Understanding the Che documentation ecosystem
• Project structure, branches and workflows
• The documentation workflow
• Reviewing a documentation pull request
• Editing, submitting and reviewing content
• Creating a page
• Creating a partial
• Adding an example specific to the project context
• Adding an image
• Using special characters
• Building and validating Documentation on a local environment
• Getting support

Understanding the Che documentation ecosystem

• See the Code of conduct.

• Use the following editorial resources:

  • Minimalism in writing.

    • The Wisdom of Crowds slides

    • The Wisdom of Crowds video

    • Chunking.

  • Style Guide

    • Red Hat Style Guide

    • Vale for writers at Red Hat

  • Guidelines from the Modular Documentation Initiative.

    Tip	For Antora, a module is a collection of content in a component version. This project is referring to Modular Documentation modules as content types. To understand the nature of topics, see the Appendix A: Modular Documentation Terms and Definitions.

• Use the Git Forking Workflow.

• Eclipse Che hosted by Red Hat is the recommended IDE to edit and build the content.

• The relevant tools for editing, validation, and publication workflows are available in the che-docs container.

  • Antora builds the documentation.

  • AsciiDoc is the markup language.

  • htmltest validates the links.

  • Vale validates the language.

  • ShellCheck validates the shell scripts.

Project structure, branches and workflows

1. main branch - hosts documentation for next version of Che.

2. release branches (e.g. 7.90.x) - hosts documentations for stable versions of Che.

3. publication branch stores published documents.

4. publication-builder branch hosts a structure and a workflow for publishing documentation to the publication branch.

Che Docs uses GitHub actions workflows for performing CI / release builds, and Pull request check jobs.

CI jobs: . build-and-validate-on-push.yaml - assemble the project by using the current che-docs:next image. Triggered on commit to the main branch . container-build - build quay.io/eclipse/che-docs:next image. . https://github.com/eclipse-che/che-docs/blob/main/.github/workflows/call-publication-builder.yml - Triggered on commit to the main or release branch. It will call a workflow from publication-builder branch to publish documentation in publication branch.

Release jobs: . Release - see Release Eclipse Che documentation.

PR Check jobs: . Build and validate pull request - assemble the project from the PR branch, using cquay.io/eclipse/che-docs:next container image. . Build and verify container - build che-docs container image. . Publish Netlify - triggered after build-and-validate-on-pr completion. Assembled documentation is deployed for preview with "Netlify" platform. . vale - Vale linting check . Try in web IDE - view pull request through Eclipse Che. See https://eclipse.dev/che/docs/stable/end-user-guide/try-in-web-ide-github-action/

The documentation workflow

Procedure

1. Contributor submits a code pull request in one of the Che repositories with a status/doc-impact label.

2. The author of the code pull request, or the reviewer ensures the code pull request contains a reference to a documentation pull request for the main branch of the che-docs repository:

   1. The author of the code pull request, or the reviewer provides a documentation pull request that the members of the documentation team can merge without further editing.

   2. Or, the author of the code pull request, or the reviewer provides at least an initial draft of the content and reaches out to the documentation-team members for assistance with editing, to help finalize the documentation pull request.

   3. Or, the author of the code pull request, or the reviewer reaches out to the members of the documentation team and work with them on submitting a documentation pull request.

3. Review the documentation pull request.

4. Merge the code pull request into the che repository, for next milestone x.y.z.

5. Merge the documentation content for next milestone x.y.z into the main branch of the che-docs repository.

6. Release che milestone x.y.z.

7. Release Eclipse Che documentation.

8. Publish Eclipse Che documentation.

Reviewing a documentation pull request

Review the pull request in the Eclipse Che hosted by Red Hat IDE.

Procedure

1. Navigate to the pull request

2. Click on the Eclipse Che hosted by Red Hat link in the comments.

3. Build and validate the documentation, and start the preview server: open Menu > Terminal > Run Tasks > che: start-preview-server.

4. In the Terminal panel, watch the output of the che: start-preview-server task to validate the result: internal and external links, language on created and changed files.

5. Navigate to the preview: open Preview.

6. Open created and changed files, and examine the Problems Panel to validate the language. Toggle the view of the Problems Panel using the View > Problems menu entry.

7. Review the pull request. See the code review checklist.

Editing, submitting and reviewing content

Prerequisites

• A fork of the https://github.com/eclipse/che-docs/ project, accessible at the following URL, where <organization> is your GitHub organization or username: https://github.com/<organization>/che-docs/. See Fork a repository.

Procedure

1. Open a che-docs workspace running on Eclipse Che hosted by Red Hat: https://workspaces.openshift.com/#https://github.com/<organization>/che-docs/.

2. Create a branch <branch-name> for your work.

3. Edit the content.

   • Creating a page

   • Creating a partial

   • Creating a partial

   • Adding an example specific to the project context

   • Adding an image

   • Using special characters

4. Build and validate the documentation, and start the preview server: open My Workspace > User Runtimes > che-docs > Start preview server.

5. Watch the output of the Start preview server task to validate the result: internal and external links, language on created and changed files.

6. Navigate to the preview: open Preview.

7. Open created and changed files, and examine the Problems Panel to validate the language. Toggle the view of the Problems Panel using the View > Problems menu entry.

8. To merge the content, open a pull request to the default main branch.

9. When you intend to review a pull request, assign yourself in the GitHub pull request view.

10. Review the pull request. See Reviewing a documentation pull request.

11. The documentation pull request needs a review by the documentation team and by engineering.

12. The continuous integration process is publishing content after the merge in the release branch.

Verification steps

• Navigate to the publication URL of Eclipse Che Documentation: https://www.eclipse.org/che/docs/ and search for your changes.

Creating a page

Create a page and add it to the navigation when:

• It is meaningful to have a navigation entry

• The content might receive cross-references. Avoid cross-references to a page fragment.

Procedure

1. Define the page destination directory <pages_directory>. It can be:

   • modules/administration-guide/pages/

   • modules/end-user-guide/pages/

2. Define the page title, and the page file name: use lower case and separate words with dashes <title>.adoc. The directory and the file name determine the page URL.

3. Copy one of the templates in the templates/pages directory to <pages_directory>/<title>.adoc.

   • Assembly page template

   • Concept page template

   • Procedure page template

   • Reference page template

4. Add a cross-reference to the page in the modules/<guide_name>/nav.adoc navigation file to create the navigation entry.

   * xref:<file_name>.adoc[]

5. Verify that an AsciiDoc attribute defines the content type. The page content type can be:

   • :_content-type: ASSEMBLY

   • :_content-type: CONCEPT

   • :_content-type: PROCEDURE

   • :_content-type: REFERENCE

6. Edit the Antora metadata in the file.

   Example 1. Template metadata for a page

   :description: A description of the page stored in an HTML meta tag.
   :keywords: comma-separated values, stored, in an HTML, meta, tag
   :navtitle: Title
   :page-aliases:
   
   [id="title"]
   = Title

7. Author the content.

Creating a partial

Create a partial and add it to an assembly page when:

• The content is a concept, procedure or reference to include in a page.

• The content might not receive cross-references.

Procedure

1. Copy one of the templates in the templates/partials directory to modules/<guide_name>/partials/<lowercase_title>.adoc.

   • Concept partial template

   • Procedure partial template

   • Reference partial template

2. Verify that an AsciiDoc attribute defines the content type. The partial content type can be:

   • :_content-type: CONCEPT

   • :_content-type: PROCEDURE

   • :_content-type: REFERENCE

3. Add an include statement in the corresponding page in modules/<guide_name>/pages/:

   include::partial$<file_name>.adoc[leveloffset=+1]

4. Edit the metadata in the file.

   [id="title"]
   = Title

5. Author the content.

Adding an example specific to the project context

Create an example specific to the project context when:

• Upstream and downstream require a different content.

• The content is a block of text.

• Using an AsciiDoc attribute is not an option.

The include statement contains the project-context attribute to ensure upstream and downstream use a different file. These snippets have no content type.

Procedure

1. Create the file modules/<guide_name>/examples/snip_che_<lowercase_title>.adoc, and author the content.

2. Add an include statement in the corresponding page templates directory to modules/<guide_name>/pages/<title>.adoc.

   include::example$snip_{project-context}<file_name>.adoc[leveloffset=+1]

3. Author the content.

Adding an image

Avoid using images unless necessary.

Procedure

1. Add the image to the modules/__<guide_name>__/images/ directory corresponding to the guide including the image.

2. To publish a block image, use the following syntax. See Antora documentation - Add block images and Asciidoctor documentation - Images.

   Example 2. Block image

   .__<Image caption>__
   image::__<image_name>__.png[__<Image title>__]

3. The publication tool resizes images. To provide a link to a full-size image, add a link attribute:

   Example 3. Block image with a link to the full-size image

   .__<Image caption>__
   image::__<image_file_name>__[__<Image title>__,link="../_images/__<image_file_name>__"]

Using special characters

Procedure

• To exclude special characters from markup substitutions, use the inline pass macro.

  Example 4. Displaying a variable name containing underscores

  pass:a,c,m[VARIABLE_NAME__WITH__UNDERSCORES]

  Result

  VARIABLE_NAME__WITH__UNDERSCORES

Building and validating Documentation on a local environment

This section describes how to build and validate the documentation on a local environment using the che-docs container.

Warning

This is not the preferred method. For the supported method, see: Editing, submitting and reviewing content.

Prerequisites:

• A running installation of podman or docker.

Procedure

1. Open a shell prompt into the project directory, and build and validate the documentation using and instance of the che-docs container.

   $ ./tools/runnerpreview.sh

2. Read the output for the results of the links and language validation steps.

3. Navigate to localhost:4000 in your browser.

Getting support

GitHub issue

• 

• 

Public Chat

• Join the public eclipse-che Mattermost channel to talk to the community and contributors.