Writing documentation in Eclipse Che

The quick and easy way to create documentation

With Eclipse Che, writing technical documentation is even easier than you think. Let’s use the Eclipse Che documentation repository on GitHub. The che-docs repository was created with community contribution in mind, featuring tools you need to create and test your content. And from the initial draft to submitting a PR, everything is happening in the environment you’re already familiar with: an Eclipse Che cloud development environment (CDE).

An Eclipse Che CDE created from the che-docs repository.

Getting started

Click the Developer Workspace button in the che-docs repository README file. This opens a clone of the repository in an Eclipse Che workspace hosted by Red Hat in the Developer Sandbox. Alternatively, you can click right here:

How does it work?

What about the che-docs repository makes using an Eclipse Che CDE to contribute content so convenient? The following two elements:

Let’s look at the devfile first. The che-docs repository contains a simple devfile that defines the basic features of the che-docs workspace. It also includes a command for building a preview of your newly created content:

# sh tools/preview.sh

This is helpful not only for checking the layout of the document but also for making sure that embedded images, links and code blocks are displayed correctly. Additionally, the preview script features a Vale-based grammar check you can also use separately. More about this in a moment.

By default, the che-docs workspace launches with Visual Studio Code - Open Source ("Code - OSS") as the IDE. This is relevant for the second file mentioned above. The che-docs repository features an extensions.json file listing Visual Studio Code extensions you need for writing Eclipse Che content. When you launch the che-docs workspace for the first time, these extensions are installed automatically:

Overview of automatically installed extensions, including the Vale extension.

You can start working immediately, with minimal additional setup required.

Getting started

By launching the che-docs workspace, you’re almost ready to go:

You have a clone of the che-docs repository
You have an IDE to write in.
You have required extensions installed.
You have a preview build script.

There are only three things left to do.

Read the contribution guidelines.
Read how to document commands for Eclipse Che documentation.
Update the grammar- and spelling-checking Vale extension by running the vale-sync command defined in the devfile or directly execute it in the terminal:
```
# vale sync
```

Note	The Vale extension included in the che-docs repository follows the grammatical, spelling and stylistic rules from the Red Hat supplementary style guide.

Writing tips

A good technical document is easy to read and easy to follow. Here are a few tips that will help you write great technical content:

Keep it simple. Avoid self-referential language ("this article is about…"), overly long introductions, and deep-dives into the feature’s history.
Keep it accessible. Short paragraphs, sentences and words make your content easy to read.
Keep the focus on the user. Write the content around what the user can achieve when they follow your instructions.
Keep passive voice to a minimum.

The famous opening lines of Jane Austen’s Pride and Prejudice novel don’t follow any of the writing tips listed in this blog post. At grade 16, they also have a very high readability score in the Hemingway Editor. Your technical document should have a readability score between grade 9 and 11.

If you want to learn more about technical writing in general, check out the Google developer documentation style guide. The readability test is a part of the Hemingway Editor.

Happy writing!