CONTRIBUTING.adoc

Table of Contents

• Contributing to the Eclipse Che documentation
  • Understanding the Che documentation ecosystem
  • The documentation workflow
  • Reviewing a documentation pull request
  • Editing, submitting and reviewing content
  • Creating a page
  • Creating a partial
  • Adding a contextual example
  • Adding an image
  • Using special characters
  • Building and validating Documentation on a local environment
  • Getting support

Contributing to the Eclipse Che documentation

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 type. 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 builds 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.

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 finalizing 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 My Workspace > User Runtimes > che-docs > Start preview server.

4. Watch the output of the Start preview server task to validate the build: 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/f?url=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 a contextual example

   • 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 build: 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 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, or when it may receive cross references. Avoid cross references to a page fragment. The file name determines the page URL. Therefore an AsciiDoc attribute defines the content type, rather than a file name prefix. The page content type can be:

• :_content-type: ASSEMBLY

• :_content-type: CONCEPT

• :_content-type: PROCEDURE

• :_content-type: REFERENCE

Procedure

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

   • Assembly page template

   • Concept page template

   • Procedure page template

   • Reference page template

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

   Example 1. Navigation entry

   * xref:<file_name>.adoc[]

3. Edit the metadata in the file.

   Example 2. 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_{context}"]
   = Title

4. Author the content.

Creating a partial

Create a partial and add it to an assembly page when it may not receive cross references. For consistency with the pages, an AsciiDoc attribute defines the content type. The partial content type can be:

• :_content-type: CONCEPT

• :_content-type: PROCEDURE

• :_content-type: REFERENCE

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. Add an include statement in the corresponding page modules/<guide_name>/pages/<title>.adoc:

   Example 3. Include statement to a partial, in a page

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

3. Edit the metadata in the file.

   Example 4. Template metadata for a partial

   [id="title_{context}"]
   = Title

4. Author the content.

Adding a contextual example

Create a contextual example when upstream and downstream need a different content. 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 an empty file modules/<guide_name>/examples/snip_che_<lowercase_title>.adoc.

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 documantation - Images.

   Example 5. 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 6. 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 7. 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.