CONTRIBUTING.adoc

Contributing to the Eclipse Che Documentation

Table of Contents

• Understanding Che Documentation ecosystem
• The documentation workflow
• Editing, submitting and reviewing new content
• Building and validating the documentation using Che
• Creating a new topic using Che
• Adding images
• Using special characters
• Building and validating Documentation on a local environment using the che-docs container
• Getting support

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

  • IBM Style Guide.

    • The IBM Style Guide, Conventions for Writers and Editors

    • A Vale-compatible implementation of IBM’s Developer Editorial Style Guide

  • 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 topics. 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 built in the che-docs container.

  • Antora builds the documentation.

  • AsciiDoc is the markup language.

  • Newdoc generates the topics templates.

  • htmltest validates the links.

  • Vale validates the language.

  • ShellCheck validates the shell scripts.

  • Test-adoc validates the topic files.

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 master branch of the che-docs repository:

   1. The author of the code pull request or the reviewer provides a complete documentation pull request that can then be merged by the members of the documentation team 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, so that the documentation pull request can be finalized.

   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. See Editing, submitting and reviewing new content.

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

5. The documentation pull request, validated, stays in the queue in the che-docs repository.

6. Release che milestone x.y.z.

7. Merge the documentation content for milestone x.y.z into the master branch of the che-docs repository.

8. Publish the che-docs master branch to https://www.eclipse.org/che/docs.

Editing, submitting and reviewing new 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.

4. Build and validate the new content. See: Building and validating the documentation using Che.

5. To merge the content, open a pull request. Submit the pull request against the default master branch. Specify as much information as possible in the pull request template.

6. When you intend to review a pull request, click Assignees in the GitHub pull request view. This indicates you are the reviewer and avoids duplication of efforts.

7. To review the pull request:

   1. See the code review checklist.

   2. For documentation updates containing testable steps, the documentation pull request needs to have the team/che-qe label set and get reviewed by both the documentation team and the Che QA team.

   3. For documentation updates not containing testable steps, the documentation pull request needs to get reviewed by the documentation team.

   4. For more information, see Building and validating the documentation using Che.

8. The continuous integration process is publishing content once merged in the master publication branch.

Verification steps

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

Building and validating the documentation using Che

To build the Eclipse Che documentation from a Che workspace, follow the steps below.

Prerequisites

• Open a Che workspace containing a fork of the documentation. See Editing, submitting and reviewing new content.

Procedure

1. To build the documentation and start the preview server: open My Workspace / User Runtimes / che-docs / Start preview server.

2. To navigate to the preview, open Preview.

3. To validate the links: open User Runtimes / che-docs / Validate links.

4. To validate the language changes: open My Workspace / User Runtimes / che-docs / Validate language changes.

5. To validate the language of the currently open files, look at the Problems tab in the Bottom Panel. To toggle the view of this tab use the View > Problems menu entry.

6. To validate the compliance of an AsciiDoc file with Modular Documentation guidelines:

   1. In the Explorer, right-click on file to validate and select Copy Path.

   2. Open My Workspace / User Runtimes / che-docs / Validate Modular Doc.

   3. In the Validate Modular Doc panel in the Bottom Panel, paste the path of the file to validate.

   4. The tool test-adoc tests the file and produces some output.

Creating a new topic using Che

To create a new topic using a Che workspace:

Procedure

1. Open My Workspace.

2. Open User Runtimes / tools / Create a new topic.

3. Choose the target guide among the available guides:

   • overview: introductory section

   • end-user-guide: documentation for developers: navigating dashboard, working in Che-Theia, and so on

   • installation-guide: installation guides

   • administration-guide: documentation for administrators of the clusters: configuring Che on a cluster, managing users, monitoring resources, security and data recovery

   • contributor-guide: how to develop plug-ins for Che, add new debuggers, languages, and so on

   • extensions: documentation about extensions for Che, such as Eclipse Che4z, OpenShift Connector.

4. Choose the topic nature:

   • assembly

   • concept

   • procedure

   • reference

5. Enter the title for the new topic.

Verification steps

1. The file is generated in the src/main/pages-che-7/<guide_name>/ directory and the script displays related information.

Adding images

Procedure

1. Add images to one of the subdirectories in the src/main/che/docs/images/ directory. Create a new subdirectory if none of the existing ones fits the new image.

2. To publish an image, use the following syntax:

   image::directory/img.png[alt text]

   Images are sized automatically. You can provide a URL to a full-size image, as well as a caption and alt text:

   .Click to view a larger image
   [link=che/docs/images/devel/js_flow.png
   image::devel/js_flow.png[Alt text]

Do not post too many images unless it is absolutely necessary. Animated .gif images are preferred, especially when explaining how to use complex UI features.

Using special characters

• To prevent special characters from being interpreted as formatting mark-up, use pass-through macros.

  Example 1. To escape underscores, asterisks, or backticks, use:

  pass:[VARIABLE_NAME__WITH__UNDERSCORES]

Building and validating Documentation on a local environment using the che-docs container

This section describes how to build and validate the documentation on a local environment.

Warning

This is not the preferred method. For the supported method, see: Building and validating the documentation using Che.

Prerequisites:

• A running installation of podman or docker.

Procedure

1. Open a terminal into the project directory, and build the documentation using and instance of the che-docs container:

   $ ./tools/runnerpreview.sh

2. Navigate to localhost:4000 in your browser.

3. Open a second terminal, and attach to the running che-docs container. Run all following steps from this context.

   $ podman exec -ti che-docs  bash

4. To validate links, run:

   $ htmltest

5. To validate language on changed files, run:

   $ ./tools/validate_language_changes.sh

6. To create a new topic using templates, run following command:

   $ ./tools/newtopic.sh

7. To validate the compliance of an AsciiDoc file with Modular Documentation standards, run:

   $ ./tools/test-adoc.sh <PATH_TO_THE_FILE>

Getting support

GitHub issue

• 

• 

Public Chat

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