Documentation Contribution Guide

Good documentation is crucial for any kind of software. This is especially true for sophisticated software systems such as distributed data processing engines like Apache Hop. The Apache Hop community aims to provide concise, precise, and complete documentation and welcomes any contribution to improve Apache Hop’s documentation.

Warning
Just like code, documentation is never done. We’re eager to find out how you think our docs can be improved, come discuss with us on our documentation channel.

About the Hop documentation

The Hop documentation and website content are written in Asciidoc. Asciidoc is a lightweight markup language which can be translated to HTML.

In order to update or extend the documentation you have to modify the Asciidoc (.adoc) files. For more information on Asciidoc check out asciidoc.org.

The Hop docs and website content are built using the Antora framework.

Check the video below for more information on the concepts and a quick introduction to asciidoc and Antora.

Types of documentation

Apache Hop has multiple types of documentation for different audiences, covering specific topics and use cases. We have a user manual for basic and more advanced instructions on how to install, use configure Apache Hop.

User manual

The goal for the user manual is to give a general feeling to how the application works, which transforms and actions are available and a guide on how to use them. A default template is used to explain how transforms and actions work, an Archetype is included in the repository to use as a template.

Technical documentation

Technical documentation contains best practices and general guidelines on how to use Hop in several environments and use cases.

API documentation

This is code documentation and only needed when you want to explore the internals of Hop or contribute code.

Work on the documentation directly from the Hop website

Every documentation page on the Hop website has a 'Edit this page' button like the one below.

Edit this page

If you click on this page, you’ll be taken directly to the github editor for that page.

After you’ve made the changes you want to make, add a description for your changes and click 'Proposed changes'.

Propose Changes

Review the entries in the pull request template and click 'Create pull request'.

Create Pull Request

Once your pull request has been reviewed, accepted and merged, the Hop build system will run a couple of checks and tests and the website needs to be rebuilt with your changes.

Tip
The pull request review and merge is a manual process. Even though it usually only takes a couple of hours at most, this process can not be fully automated, so don’t expect your changes to appear immediately.

Work on the documentation asciidoc

All Apache Hop documentation is maintained in the same git repository as the code base.

User manual and Technical documentation

The easiest way to contribute documentation is to fork Hop’s repository on GitHub into your own GitHub account by clicking on the fork button at the top right. If you have no GitHub account, you can create one for free.

Next, clone your fork to your local machine.

git clone https://github.com/<your-user-name>/incubator-hop.git

The user manual documentation is located in the docs/hop-user-manual/ subdirectory. The technical documentation is located in the docs/hop-tech-manual/ subdirectory.

API documentation

To contribute to the API and code documentation create a fork of Hop’s code repository.

git clone https://github.com/<your-user-name>/incubator-hop.git

The API documentation is located in the docs/hop-dev-manual subdirectory

Before you start start working on the documentation…​

Please make sure you have a Jira issue that corresponds to your contribution. We require all documentation changes to refer to a Jira issue, except for trivial fixes such as typos.

Documentation translations

We are planning on providing all documentation in multiple languages. We are looking for contributors that want to work with us and make this possible! If you are interested to maintain a translation language feel free to contact us on our chat.

Submit your contribution

Apache Hop accepts documentation contributions through the GitHub as Pull Requests. Pull requests are a simple way of offering a patch by providing a pointer to a code branch that contains the changes.

To prepare and submit a pull request follow these steps.

Commit your changes to your local git repository. The commit message should point to the corresponding Jira issue by starting with [HOP-XXXX].

Push your committed contribution to your fork of the Hop repository at GitHub.

git push origin myBranch

Go to the website of your repository fork (https://github.com/<your-user-name>/incubator-hop) and use the “Create Pull Request” button to start creating a pull request. Make sure that the base fork is hop master and the head fork selects the branch with your changes. Give the pull request a meaningful description and submit it.

It is also possible to attach a patch to a Jira issue.