How to Report Bugs or Contribute Corrections to the hello-algo Documentation

Question

Learn how to report bugs or contribute corrections to the hello-algo documentation. Follow our simple guide to submitting GitHub issues or pull requests for content updates.

Accepted Answer

To report bugs or contribute corrections to the hello-algo documentation, open a GitHub issue for discussion or submit a pull request modifying the Markdown source files in the language-specific */docs/ directories, following the two-reviewer workflow defined in en/CONTRIBUTING.md or ja/CONTRIBUTING.md.

The hello-algo repository is an open-source algorithm learning resource built as a static site using MkDocs. If you spot typos, broken links, or unclear explanations, you can report bugs or contribute corrections to the hello-algo documentation through a structured GitHub workflow that ensures quality across multiple language versions.

Understanding the Documentation Structure

The documentation is organized as a MkDocs project with language-specific content directories. Each translation lives in its own folder with a docs/ subdirectory containing the Markdown source files.

English content: en/docs/
Japanese content: ja/docs/
Traditional Chinese content: zh-hant/docs/

The site configuration resides in mkdocs.yml at the repository root, while global style overrides are defined in overrides/stylesheets/extra.css.

Reporting Bugs in hello-algo Documentation

For non-trivial bugs or content errors that require discussion, opening a GitHub issue is the preferred first step.

Navigate to the Issues tab in the krahets/hello-algo repository. Create a new issue with a clear, descriptive title that identifies the problem. In the description, specify the exact file path and line number where the error occurs, using the format en/docs/chapter_tree/binary_tree.md: line 42. Include a brief explanation of the bug and, if applicable, suggest the correct information or wording.

Contributing Corrections via Pull Request

For straightforward fixes like typos, grammar corrections, or link updates, submit a pull request directly following the project's contribution workflow.

Step 1: Review the Contribution Guidelines

Before making changes, read the language-specific contribution guide. The English workflow is documented in en/CONTRIBUTING.md, while the Japanese workflow is in ja/CONTRIBUTING.md. These files describe the translation validation pipeline, commit message conventions, and the requirement that two reviewers must approve any pull request before merging.

Step 2: Fork and Branch

Fork the repository on GitHub, then clone your fork locally and create a dedicated branch for your fix.


# Clone your fork

git clone https://github.com/<your-username>/hello-algo.git
cd hello-algo

# Create a feature branch

git checkout -b fix-typo-binary-tree

Step 3: Edit the Markdown Source

Locate and edit the specific Markdown file within the appropriate */docs/ directory. For example, to fix a typo in the English binary tree chapter, edit en/docs/chapter_tree/binary_tree.md.

Make your corrections directly in the Markdown source, ensuring you preserve the existing formatting and frontmatter structure.

Step 4: Local Preview with MkDocs (Optional)

Verify your changes render correctly by running the local MkDocs server.


# Install dependencies

pip install mkdocs mkdocs-material

# Serve the site locally

mkdocs serve

Open http://127.0.0.1:8000 in your browser to preview the documentation. This step is optional but recommended for structural changes or formatting fixes.

Step 5: Commit and Push

Stage your changes and commit with a descriptive message following conventional commit style.

git add en/docs/chapter_tree/binary_tree.md
git commit -m "fix: correct typo in binary_tree.md (line 42)"
git push origin fix-typo-binary-tree

Step 6: Open the Pull Request

Navigate to your fork on GitHub and click "Compare & pull request". Target the main branch of krahets/hello-algo.

In the PR description, reference any related issue (e.g., Fixes #123) and describe the correction. The PR template will prompt you to confirm you have followed the review checklist from the contribution guide.

Note that two reviewers must approve your pull request before it can be merged into main. If reviewers request changes, address the feedback by pushing additional commits to your branch.

Key Files for Contributors

Understanding the repository layout helps you navigate the codebase efficiently.

en/CONTRIBUTING.md – English contribution workflow and PR requirements
ja/CONTRIBUTING.md – Japanese contribution guidelines
mkdocs.yml – MkDocs site configuration and navigation structure
*/docs/ – Language-specific Markdown source files (e.g., en/docs/, ja/docs/)
overrides/stylesheets/extra.css – Global CSS overrides affecting documentation appearance

Summary

Report bugs or contribute corrections to the hello-algo documentation by opening GitHub issues for discussion or pull requests for direct fixes.
All documentation source files reside in language-specific */docs/ directories (e.g., en/docs/, ja/docs/).
Follow the contribution guidelines in en/CONTRIBUTING.md or ja/CONTRIBUTING.md, which require two reviewer approvals for every pull request.
Use MkDocs to preview changes locally by running mkdocs serve after installing mkdocs-material.

Frequently Asked Questions

Do I need to open an issue before submitting a pull request for a typo?

No. For straightforward corrections like typos, broken links, or minor grammar fixes, you can submit a pull request directly without opening a separate issue. However, for structural changes, content inaccuracies, or controversial wording, opening an issue first is recommended to discuss the approach with maintainers.

How many reviewers need to approve my documentation pull request?

According to the workflow defined in en/CONTRIBUTING.md and ja/CONTRIBUTING.md, two reviewers must approve your pull request before it can be merged into the main branch. This requirement ensures quality and consistency across the multilingual documentation.

Can I contribute corrections to non-English versions of the documentation?

Yes. The repository maintains parallel documentation in multiple languages, each in its own directory (e.g., ja/docs/ for Japanese, zh-hant/docs/ for Traditional Chinese). Each language has its own contribution guide (e.g., ja/CONTRIBUTING.md) that may contain specific validation rules for that translation.

What should I do if my change affects consistency across multiple languages?

If your correction involves a concept, term, or code example that appears in multiple language versions, add a comment in your pull request highlighting the potential consistency impact. The maintainers can then assess whether the change should be propagated to other language directories or if language-specific variations are intentional.