-
Notifications
You must be signed in to change notification settings - Fork 13
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
* che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * che docs contribution * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * che docs contribution * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Artem Zatsarynnyi <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc Co-authored-by: Ilya Buziuk <[email protected]> * Update _posts/2024-08-09-contributing-to-eclipse-che-docs.adoc --------- Co-authored-by: Ilya Buziuk <[email protected]> Co-authored-by: Artem Zatsarynnyi <[email protected]>
- Loading branch information
1 parent
0435bf0
commit 0c175f0
Showing
4 changed files
with
111 additions
and
0 deletions.
There are no files selected for viewing
111 changes: 111 additions & 0 deletions
111
_posts/2024-08-09-contributing-to-eclipse-che-docs.adoc
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,111 @@ | ||
--- | ||
title: Writing documentation in Eclipse Che | ||
layout: post | ||
author: Jana Vrbkova | ||
description: >- | ||
Write documentation using an Eclipse Che CDE. | ||
categories: [] | ||
keywords: ['che-docs', 'documentation', 'write', 'contribute'] | ||
slug: /@deerskindoll/writing-docs-with-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 link:https://github.com/eclipse-che/che-docs[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). | ||
|
||
image::/assets/img/contributing-to-eclipse-che-docs/workspace-with-preview.png[An Eclipse Che CDE created from the che-docs repository.] | ||
|
||
|
||
== Getting started | ||
|
||
Click the Developer Workspace button in the che-docs repository link:https://github.com/eclipse-che/che-docs?tab=readme-ov-file#eclipse-che-documentation-project[README] file. | ||
This opens a clone of the repository in an Eclipse Che workspace hosted | ||
by Red Hat in the link:https://developers.redhat.com/developer-sandbox[Developer Sandbox]. | ||
Alternatively, you can click right here: | ||
|
||
[link=https://workspaces.openshift.com#https://github.com/eclipse/che-docs] | ||
image::https://www.eclipse.org/che/contribute.svg[] | ||
|
||
== 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: | ||
|
||
* link:https://eclipse.dev/che/docs/stable/end-user-guide/devfile-introduction/[devfile] | ||
* list of link:https://eclipse.dev/che/docs/stable/end-user-guide/microsoft-visual-studio-code-open-source-ide/#automating-installation-of-microsoft-visual-studio-code-extensions-at-workspace-startup[automatically installed Microsoft Visual Studio Code extensions] | ||
|
||
Let's look at the devfile first. | ||
The che-docs repository contains a simple link:https://github.com/eclipse-che/che-docs/blob/main/devfile.yaml[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: | ||
|
||
[source, code] | ||
---- | ||
# 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 link:https://github.com/eclipse-che/che-docs/blob/main/.vscode/extensions.json[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: | ||
|
||
image::/assets/img/contributing-to-eclipse-che-docs/extensions.png["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 link:https://github.com/eclipse-che/che-docs/blob/main/CONTRIBUTING.adoc[contribution guidelines]. | ||
. Read how to link:https://redhat-documentation.github.io/supplementary-style-guide/#technical-examples[document commands] for Eclipse Che documentation. | ||
. Update the grammar- and spelling-checking link:https://marketplace.visualstudio.com/items?itemName=ChrisChinchilla.vale-vscode[Vale extension] by running the `vale-sync` command defined in the link:https://github.com/eclipse-che/che-docs/blob/main/devfile.yaml[devfile] or directly execute it in the terminal: | ||
+ | ||
[source, code] | ||
---- | ||
# vale sync | ||
---- | ||
|
||
[NOTE] | ||
==== | ||
The Vale extension included in the che-docs repository follows the grammatical, | ||
spelling and stylistic rules from the link:https://redhat-documentation.github.io/supplementary-style-guide/[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. | ||
|
||
image::/assets/img/contributing-to-eclipse-che-docs/pp-hemingway.png["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 link:https://developers.google.com/style[Google developer documentation style guide]. | ||
The readability test is a part of the link:https://hemingwayapp.com/[Hemingway Editor]. | ||
|
||
Happy writing! |
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
Binary file added
BIN
+815 KB
assets/img/contributing-to-eclipse-che-docs/workspace-with-preview.png
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.