Contributing to the documentation

GitHub

Workflow

  1. If necessary, create an issue, before working on it, and assign yourself to the issue.

  2. Start Working on an issue

  3. Create a PR

  4. Finalize the PR until the reviewers approve it.

  5. Merge: Wait for the PR to merged by the Docs Lead. This will also close the corresponding issue automatically.

  6. Deployment on production by Docs Lead.

Issues

Creating issues

Please create new issues concerning the Lisk documentation at github.com/LiskHQ/lisk-docs/issues.

Avoid posting redundant issues: Check before, if someone has already opened an issue concerning the topic.

  • Templates:

    • Use the template Bug for any errors or anomalies that you have found inside the documentation.

    • Use the Feature template for further ideas on improving the documentation (e.g. structural changes of content or adding additional content).

    • Use the Update template for content that is outdated.

    • Use the Improvement template for content that needs improvement.

  • Title: Choose a clear self-explanatory title.

  • Description:

    • Provide a detailed description of the issue.

    • Mention which components and versions are affected by the issue.

      Example of an issue description
      A detailed description of the issue.

Affected branch: `docs-sdk` (1)
      1 Always specify the branch, that is affected by the issue.

  • Labels:

    • component labels

    • category labels

  • Projects: If the issue belongs to a particular project, specify it in the issue.

Epics and child issues

An epic issue is an issue that needs several PRs for it to be solved.

If an issue affects multiple branches, it is always an epic issue.
Example of an epic issue description
### Problem
The content describing the documentation strategy is all in one document which doesn't provide a good overview regarding all of its contents.
Furthermore, some of the required content is outdated or not existent yet.

### Describe the solution you would prefer to see
A new documentation component `docs-manual` should be created. This component will contain 2 new modules:
- A new documentation module `styleguide` should contain all guidelines and best practices regarding the style of writing in the Lisk documentation.
- A new documentation module `build` should contain all steps and guidelines about how the content of the docs is structured, and prepared for production.

- [ ] Add new documentation module `styleguide` (1)
- [ ] Add new documentation module `build` #754 (2)
1 Break the epic issue down into child issues, and list the tasks below the description of the epic issue.
2 If a child issue was already created, refer to the issue ID.

Working on an issue

  1. Communicate to the team that you want to work on a specific issue in the Sprint planning meeting. Alternatively, announce you will work on an unplanned issue in the daily standup or in the lisk-docs channel on Slack.

  2. To start work on an issue, assign yourself to it.

  3. Then check out the base branch, here development, and create a new branch named after the issue you are working on:

    git checkout development
git checkout -b 123-issue-title

    where 123 should be the corresponding issue number.

  4. Start to make your changes and commit them.

  5. Then push them back to the lisk-docs repository on GitHub:

    git push origin 123-issue-title

Projects

Always add the issues and PRs to the corresponding project(s).

For an overview about the existing projects, please check github.com/LiskHQ/lisk-docs/projects?type=beta.

Pull requests (PRs)

Creating a PR

  1. On GitHub, open a PR and check the correct base branch (should be development, or one of the product-specific content branches.

  2. Use Closes #ISSUENUMBER in the description. Check, if the issue is also linked on the right side panel.

  3. Add the PR to the same project as the corresponding issue.

  4. Click on Create pull request to create the PR which is ready for review, or Create draft pull request to create a PR that is still work in progress.

  5. Request a reviewer, once the PR is ready from your side.

Local preview

For viewing the docs locally, you just need to compile them with antora:

antora site.yml --fetch

Check the guide Previewing the docs locally for more information.

Merge

Once the PR is approved by at least one reviewer, the PR will be merged into the respective base branch.

The corresponding issue should close automatically, if linked. If not, close it manually once the PR which is solving the issue is merged.