How to contribute to Kadena documentation

Thank you for your interest in contributing to documentation for the Kadena blockchain and the Kadena community. As a member of the community, you are invited and encouraged to contribute to the Kadena technical documentation. There are a lot of ways to get involved. For example, you can contribute by:

• Submitting issues.
• Offering suggestions for improvements to existing content.
• Adding review comments to existing pull requests.
• Proposing new content.
• Creating new pull requests to fix issues yourself.
• Creating pull request for new content other community members might find useful.

This guide describes how you can make changes to the documentation website directly by editing source files or indirectly by requesting updates.

Before you begin

To follow the steps in this guide, verify the following basic requirements:

• You have a code editor, a GitHub account, and experience using command-line programs, including git commands and command-line options.

• You are familiar with using Markdown to add formatting elements to plain text documents. For information about using Markdown, see the Markdown Guide.

• You have the yarn package manager installed.

  You can run yarn --version to verify that you have yarn installed and the version you are running.

Get started

You can contribute to documentation by editing existing pages in the GitHub repository or by setting up a local documentation environment.

If you want to make a simple fix on an existing page—for example, to fix a typo or make minor changes to a sentence—you can edit documentation pages directly in its GitHub repository.

To edit an existing page:

1. Open docs.kadena.io and navigate to the page you want to change.

2. Click Edit this page to open the page in its GitHub repository.

3. Edit the page in GitHub, then click Commit changes.

4. Replace the default commit message with a short description of your change and, optionally, an extended description of the change or why you're proposing the change.

5. Select Create a new branch for this commit and start a pull request, then click Propose changes.

6. Add any additional information to the title or description of the pull request, then click Create pull request.

   Your pull request will be reviewed by a Kadena team member and merged, if approved.

Set up a local development environment

The Kadena Developer Documentation website is built using Docusaurus, a modern static website generator. If your contribution is more than a simple change, you'll most likely need to set up a local development environment where you can build and test the documentation that you are proposing to change. The following steps summarize what you need to do.

To set up a local development environment for contributing to Kadena documentation:

1. Open a terminal shell on your computer.

2. Clone the kadena-docs repository by running the following command:

   git clone git@github.com:kadena-docs/kadena-docs.git

3. Change to the root of the kadena-docs repository by running the following command:

   cd kadena-docs

4. Install the dependencies for the site by running the following command:

   yarn

5. Start the local development server and open up a browser window by running the following command:

   yarn start

   All of the content for the Kadena Developer Documentation website is located in the docs directory and its subdirectories. To contribute to documentation, you typically only need to work in the docs folder, its subfolders, and in individual Markdown (.md) pages.

Preview documentation changes

To preview your documentation changes locally:

1. Navigate to the docs directory: cd docs
2. Start the Docusaurus development server: npm run start
3. Open your browser and go to http://localhost:3000

Create working branches and pull requests

After you set up a local environment for contributing to documentation, you'll need to create local branches for your pull requests. In most cases, you should strictly limit the changes you include in any single pull request.

To create a working branch:

1. Use git switch -c to create a local branch with a prefix that identifies you as the author and a branch name that describes the content you intend to add or change by running a command similar to the following:

   git switch -c my-identifier-prefix/my-branch-name-here

   For example, if your git handle is lola-pistola and you are fixing a typo in the reference folder, you might create a branch like this:

   git switch -c lola-pistola/typo-reference-db-functions

2. Open the file you want to fix in a code editor and make the appropriate changes for the issue you are trying to address.

3. Add the file you changed to the list of staged commits by running a command similar to the following:

   git add path-to-changed-file

4. Commit the staged changes with a descriptive commit message by running a command similar to the following:

   git commit -m "docs: Fix db function type"

5. Push the changes to the remote repository by running a command similar to the following:

   git push origin my-identifier-prefix/my-branch-name-here

6. Click Create pull request to start a new pull request and provide any additional information about the changes you made.

   A member of the Kadena team will review your pull request and approve or request changes. If no changes are required, the Kadena team member will merge your pull request. If a Kadena team member requests changes or clarification, update your pull request and request another review.

7. When you see your changes have been merged, celebrate your success! 🥂

What to contribute

Most contributions from the community typically involve corrections or updated examples. However, you can also make valuable contributions in the form of how-to guides or tutorials that help other developers solve specific problems, learn specific skills, or demonstrate specific tasks or by translating topics into a new language.

If you would like to contribute, you might be wondering “What is the difference between a ‘how-to’ guide and a tutorial?”.

How-to guides

A how-to guide describes how to achieve a goal or complete a task. Only the information that is pertinent to achieving that goal or completing the task is included. With how-to guides, readers have enough information to know what they want to do—for example, open a bank account—but not necessarily enough information to know how to do it. For example, the how-to guide for opening a bank account wouldn't explain what a bank account is or why you might want to open one, but would focus on specific steps such as:

1. Select an institution.
2. Fill out an application.
3. Deposit a minimum amount of currency.

Tutorials

A tutorial is a hands-on illustration or lesson that enables the reader to achieve a highly-predictable result. Tutorials assume that readers have no prior knowledge on the subject being covered and that they require explicit guidance to complete each step to reach a well-known outcome. A tutorial is like a guided tour that helps the reader complete one organic task from start to finish. For example, a tutorial for opening a bank account would identify an example institution, explicitly describe what to enter for every field of the application using sample information, and specify exactly how much currency to deposit.

The single most important aspect of a tutorial is that it should always result in a successful, expected outcome that inspires confidence and delight in the reader.

The single most important distinction between a how-to guide and a tutorial is that, in a tutorial, the author decides what the goal should be and the author eliminates all distractions that would detract from the successful achievement of the goal.

Translations

To translate Kadena documentation:

1. Copy the docs folder and rename it to docs-[LANG].

   For example, create a folder named docs-es for translating topics into Spanish.

2. Translate the content in the new folder.

3. Update the Docusaurus configuration to include the new language.