Skip to main content

Contributing to Archway docs

Thank you for considering making contributions. We appreciate your interest in helping us to create and maintain awesome tutorials and documentation.

Using this repo#

Review existing Archway issues to see if your question has already been asked and answered.

  • To provide feedback, file an issue and provide generous details to help us understand how we can make it better.
  • To provide a fix, make a direct contribution. If you're not a member or maintainer, fork the repo and then submit a pull request (PR) from your forked repo to the develop branch.
  • Start by creating a draft pull request. Create your draft PR early, even if your work is just beginning or incomplete. Your draft PR indicates to the community that you're working on something and provides a space for conversations early in the development process.

Writing and contributing#

We welcome contributions to the docs, tutorials and guides.

Our technical content follows the Google developer documentation style guide. Highlights to help you get started:

The Google guidelines include more material than is listed here and can be used to guide your decision making about proposed content changes.

Other useful resources:

Where can I find the tutorials and docs?#

Developer docs:#

Developer docs refers to documentation for smart contract and dApp developers. It's content to help users build and scale dApps on Archway network and contains information that is pertinent to:

Developer docs are located in folder /docs/create of the repository.

Developer guides (tutorials):#

Developer guides are tutorials for developing Archway smart contract and dApp projects. Each guide includes step by step instructions and final source code for a completed project to be run on Archway network.

Developer guides are located in the folder /docs/create/guides

Node operator docs:#

Node operator docs refers to documentation relevant to operators of full nodes, local testnets and to connecting nodes to public networks. This content is to help with setting up, configuring, monitoring and troubleshooting node instances.

Node operator docs are located in /docs/node.

Validator docs:#

Validator docs refers to documentation relevant to operators of validator nodes, validator security and participating in validator rewards.

Validator docs are located in /docs/validator.

Viewing web app builds#

There are two ways to see what your changes will look like in production before the updated pages are published.

  • When a PR is ready for review, you can see a deployed preview on a URL that is unique for that PR.
  • While a PR is in draft mode, you can preview a local build.

Preview draft PRs on a local web browser#

Since the deploy preview doesn't work on Draft PRs, follow these steps to preview a build of the Archway docs website on a local web browser.

  1. If you haven't already, clone the docs repo to your local machine and change to that directory

    git clone git@github.com:archway-network/archway-docs.gitcd archway-docs
  2. Building the Archway docs website requires Node and npm for JavaScript.

tip

For running Docusaurus 2 we recommend using Node version 14 (fermium). Docusuarus fails to compile correctly in more recent, stable versions.

For installing and maintaining multiple versions of node and npm you can use nvm

  1. Using npm, install the repository's dependency modules

    npm install
  2. Start a local instance of the Archway docs website:

npm start

A successful compile and bootstrap of the web application looks like:

archway-docs@1.0.0-alpha startdocusaurus start --port 8080
╭────────────────────────────────────────────────────────────────────────────────────────╮│                                                                                        ││                     Update available 2.0.0-beta.6 → 2.0.0-beta.15                      ││                                                                                        ││   To upgrade Docusaurus packages with the latest version, run the following command:   │npm i @docusaurus/core@latest @docusaurus/preset-classic@latest             ││                                                                                        │╰────────────────────────────────────────────────────────────────────────────────────────╯
Starting the development server...Docusaurus website is running at "http://localhost:8080/".
✔ Client  Compiled successfully in 11.38s
ℹ 「wds」: Project is running at http://localhost:8080/ℹ 「wds」: webpack output is served from /ℹ 「wds」: Content not from webpack is served from /home/archway-docsℹ 「wds」: 404s will fallback to /index.html
  1. You can now view the docs site in your web browser using the URL http://localhost:8080/. Hot-reload is enabled. That means you won't need to stop and restart the server everytime you make changes to the docs or code.

Preview PRs on a deployed preview#

After the PR moves from Draft to Ready for review, the CI status checks will automatically generate a deploy preview. As you continue to work and commit new changes to the same branch, while the PR is open, the deploy preview will be kept up to date with your latest pushed change set.

To view a deploy preview on a Ready for review PR, click the preview link in the comment by the github-actions bot in the PR Conversation tab of the PR:

deploy-preview

Who works on the docs?#

The docs and guides are maintained by @drewstaylor, @santanaluiz and @aelesbao with contributions from the entire Archway team and folks like you.