Contributing to these Docs

Instructions for contributing to Alchemy's Open Source Docs

Github Repository: https://github.com/alchemyplatform/alchemy-docs


Why Contribute?

Web3 was built to make traditionally inaccessible industries, knowledge, and power, widely available to everyone - no matter what. However, this bold mission comes at a cost of complexity. It can be extremely challenging to break into the web3 space as a developer due to the intricate nature of blockchain technology.

This is where documentation comes in. We need resources, guides, and tutorials from the beginner to the expert level, that teaches people how to build things. No one is more qualified to do this than the builders themselves.

Almost everyone who has built in web3 has, at one point or another, felt frustrated with the lack of resources or explanations when developing, ranging from deploying your first smart contract to creating complex defi tools. However, those same developers oftentimes persevere and figure out how to build it anyways. If this is you, come write a tutorial about it! Odds are, hundreds of other developers felt the same way and gave up - you have an extremely unique opportunity to massively impact their experience, and get rewarded for doing so.

Yes, we are giving out rewards for people who contribute! These include but are not limited to:

  • Free Alchemy credits to help fuel your dApps
  • Exclusive Beta access to new Alchemy features
  • VIP support for your Alchemy account
  • Free Alchemy Swag
  • Twitter shout-out from the Alchemy account

*Note: The type of award given will be determined on a case-by-case basis


Identifying An Area to Contribute:

If you have a specific contribution in mind, confirm whether the contribution is appropriate by first reaching out to an admin in the Alchemy Discord group directly.

If you do not have a specific contribution in mind but are generally interested in adding to the open-source community, we are looking for everything ranging from edits, and updates to outdated commands, to how-to guides/tutorials. Here's a non-exhaustive list of potential areas for you to explore:

  • Developer Content Projects 🦾
    • How-to guides/tutorials
      • ex: How to monitor pending transactions
  • General Content Projects 📝
  • Maintenance Projects 🛠️
    • Maintain tutorials/docs to keep them up-to-date
      • If you get to a command in a tutorial that's out of date or has been replaced with a new best practice- update it!
    • Find and fix typos
    • Add additional helpful context / tips
    • Raise issues for other contributors to address
  • Fix an existing issue

Contribute Alchemy Docs:

There are three ways to contribute to the Alchemy Docs:

  1. Make a pull request (PR) with changes
  2. Submit a new repository to be merged
  3. Submit an issue

📘

NOTE

If you _**_want your Github to be featured on the Alchemy Docs for your contributions, please submit a pull request with your changes

1. Make a Pull Request with Changes

Repository: https://github.com/alchemyplatform/alchemy-docs

Please note that our docs are written in the Markdown. For more info about Markdown check out this cheat-sheet. For all submitted changes to the Alchemy Docs, please submit a pull request on Github for review by following the steps below:

1. Clone the Alchemy Docs repo

git clone https://github.com/alchemyplatform/alchemy-docs.git

2. Navigate to the appropriate files / make your edits to your local repo.

When making edits to files, include descriptive commit messages to ensure that Community Maintainers are able to understand and follow your train of thought.

git commit -m "fixed typo on Enhanced API page"

3. Push your local repo and submit a pull request to merge your local repo to the master Alchemy Docs repo.

For example, if you wanted to submit a pull request for a specific part of the Alchemy Docs, you would navigate to https://github.com/alchemyplatform/alchemy-docs/pulls and submit a pull request through the UI.

(Don't forget to select the appropriate branches you wish to merge!)

530

4. The Alchemy team / Community Maintainers will review the PR or reach out accordingly either approving it or contacting you to edit it.

Sample edit PR: https://github.com/alchemyplatform/alchemy-docs/issues/2

2. Submit a new Repository to be Merged

If submitting a new tutorial or document and not a change on the Alchemy Docs directly, it is recommended to have a detailed summary/introduction as part of the README to help Community Maintainers understand what content is being added and to help developers follow along.

See https://github.com/alchemyplatform/Alchemy-Notify-Tutorial for a sample tutorial that was previously accepted to the Alchemy Platforms repo.

To submit a larger document/file like the Alchemy Notify Tutorial, please reach out to the Community Maintainers through Discord and send us a link to your public repo. We will review the code and content, verify the accuracy, and suggest any edits. If the repo is ready for pulling into the Alchemy Platform repo, we will pull your repo and place it within the Official Alchemy Github Page.

3. Submitting Issues:

If you notice any particular bugs, mistakes, or unclear components in published docs, but are unable to fix the issue yourself, feel free to raise an issue to help guide contributors who are looking for items to work on!

If you find an issue with a particular part of docs and want to flag it for others to fix, navigate to the appropriate Github page containing the page that the tutorial resides within.

For example, if you wanted to submit an issue with https://github.com/alchemyplatform/Alchemy-Notify-Tutorial, you would navigate to https://github.com/alchemyplatform/Alchemy-Notify-Tutorial/issues and submit an issue through the UI.

( Don't forget to raise an appropriate flag for the issue at hand!)

For issues that cannot be easily conveyed through the Github issues tab, please reach out to the Community Maintainers through Discord or email.


Github Contribution Guidelines:

To best provide valuable content for developers and the Alchemy community at large, we defined a few general guidelines to help steer contributions.

  • Size: Please try to keep pull requests small when possible. Alchemy prefers small pull requests to give more detailed feedback and granular updates. If a large pull request is not for a single cohesive idea/tutorial, we may ask that you break it into smaller components for review.
  • Quality: Code and content as a whole should come with descriptive commit messages and quality assurance such that it is easy for peer-review and unlikely to break functionality with existing content.
    • If you add API calls within your pull request, please ensure that you include an example payload/request and an example expected response!

ReadMe