Contributing to Documentation

This guide explains how to contribute to the Bonsol documentation through GitHub. All our documentation is stored in the gitbook/ directory of our repository and synchronized with GitBook.

Understanding the Documentation Structure

Our documentation follows this structure:

• gitbook/README.md - The main landing page of the documentation

• gitbook/SUMMARY.md - Defines the structure and navigation of the documentation

• gitbook/core-concepts/ - Conceptual information about Bonsol

• gitbook/getting-started/ - Guides for new users

• gitbook/developers/ - Resources for developers

• gitbook/provers/ - Information for provers

• gitbook/contributing/ - Guidelines for contributors (including this document)

How to Add or Update Documentation

1. Fork and Clone the Repository

1. Fork the Bonsol repository on GitHub

2. Clone your fork locally:

   git clone https://github.com/YOUR-USERNAME/bonsol.git
   cd bonsol

2. Create a New Branch

Create a new branch for your documentation changes:

git checkout -b docs/your-documentation-change

Use a descriptive name that indicates what you're documenting.

3. Making Documentation Changes

Adding a New Page

1. Create your new markdown file in the appropriate subdirectory in gitbook/

2. Add a reference to your new file in gitbook/SUMMARY.md to make it appear in the navigation

Example SUMMARY.md addition:

## Getting Started

* [Installation](getting-started/installation.md)
* [Quickstart](getting-started/quickstart.md)
* [Your New Page](getting-started/your-new-page.md)

Updating Existing Content

Simply edit the relevant markdown files in the gitbook/ directory.

Markdown Guidelines

• Use clear headings with proper hierarchy (# for title, ## for sections, etc.)

• Add code examples with proper syntax highlighting:

  ```rust
  fn main() {
      println!("Hello, Bonsol!");
  }
  ```

• Use relative links when referencing other documentation pages

• Include screenshots or diagrams when they help explain concepts

• Follow our style guide for consistent documentation

4. Preview Your Changes

You can also use standard Markdown previewers to check your content.

5. Create a Pull Request

1. Commit your changes:

   git add gitbook/
   git commit -m "docs: add documentation for X feature"

   Follow our commit message guidelines with the type "docs".

2. Push to your fork:

   git push origin docs/your-documentation-change

3. Create a pull request on GitHub

   • Reference any related issues

   • Provide a clear description of what documentation you've added or updated

   • Request review from relevant team members

Documentation Style Guide

To maintain consistent documentation:

• Use present tense and active voice

• Be concise but thorough

• Include examples where appropriate

• Use sentence case for headings

• Link to relevant documentation sections

• Keep paragraphs short and focused

GitBook Specific Features

Our documentation takes advantage of several GitBook features:

Page Icons

You can add an icon to your page by including this at the top of your markdown file:

---
icon: name-of-icon
---

Internal Page References

To reference another page in the documentation:

[Title of Page](../path/to/page.md "mention")

Questions?

If you have any questions about contributing to documentation, please open an issue on GitHub or contact the team through our community channels.

Thank you for helping improve Bonsol's documentation!