Hello, #DEVCommunity! My name is Brandon and I'm a Content Contributor from the Free Team at Codecademy. For the past few months, we've collaborated in a company-wide effort and delved into the world of user-generated content (UGC) as it relates to code documentation. This post talks about that product, Codecademy Docs and how to contribute!

What is Docs?

Codecademy Docs is a free, open-contribution resource that has an ever-growing collection of entries spanning many languages and frameworks, including:

• C++
• CSS
• HTML
• JavaScript
• React
• SQL

Currently, more than 700 entries have been submitted and edited by learners from across the world... and counting! Docs was also recently added on Product Hunt and has already amassed over 150 upvotes.

How does it work?

Docs is built by the community and maintained by Codecademy. Every time a new/edited entry goes live, all the contributors involved are credited on the "Contributors" list for that entry.

Docs Github repo

All of the changes to Docs are housed in the Codecademy/docs repo on GitHub.

The "Pull requests" tab contains any open PRs pertaining to Docs entries.

Answering an issue

Issues are ideally created by Docs maintainers in the "Issues" tab to request new entries, edits, or bug fixes. However, this is the place where many contributors go to pick a subject that is appealing and create entries about them.

If you see an issue that you'd like to work on, select it and leave a comment on the thread. Someone from our team will reach out!

Creating a new entry

1. Fork the Docs repo and clone locally

To mitigate any conflicts when merging changes, we recommend that you fork the Codecademy/docs repo.

From your forked Docs repo (or your remote repo), you can then clone it onto your local machine using the repo URL (I usually go with the HTTPS one). This will create your local repo.

git clone https://github.com/github_username/docs.git

Before working on any new changes, always make sure sure that your forked main branch is even with the original Codecademy/docs:main branch. You do this by clicking "Fetch Upstream" and then "Fetch and Merge" on your remote repo:

Then, pull those changes down to your local repo (make sure you're on your main branch):

git checkout main
git pull

2. Create and switch into separate branch

Another important part of contributing to the Docs repo is to never push changes from your forked repo's main branch. This is because reviewers and maintainers may want to test your changes on their own forks. However, they can't do this if the name of the branch they're pulling from is also called main. Therefore, do the following, always create and switch into a separate branch before editing files:

git checkout -b separate-branch

3. Edit and save the file.

In this step, go ahead and make all the necessary changes to the file and save afterwards. When contributing to Docs, you should only work on a single entry (a single file) at a time.

4. Run add, commit, then push to separate branch

Tip: I run git status before following this step just to see which files are staged vs. unstaged for commit.

When finished making changes, we can add (or stage) the files for commit:

git add <space-separated list of files here>
git commit -m "brief summary of changes."

This next part is crucial: we're gonna push the changes up to the branch we created in the last step.

git push origin separate-branch

This will cause a remote-equivalent of the branch to be created on GitHub and, by extension, trigger a prompt to create a new pull request.

Note: The origin remote is the connection between your local repo and the remote repo.

git remote -v
origin  https://github.com/github_username/docs.git (fetch)
origin  https://github.com/github_username/docs.git (push)

Editing an existing entry

There are two distinct methods for editing an existing Docs entry:

• By following the same steps listed in the previous section.
• By editing the file and committing the changes directly on GitHub.

For the second method, a great place to start is from a live entry on the Docs site.

Near the top-right corner of the page for any Docs entry is an "Edit this page on GitHub" link to the equivalent file on the Docs repo, ready for editing!

After making changes, scroll down near the bottom to find a prompt for committing the changes and submitting a pull request.

Inside this prompt, you can:

• Give the commit a specific name and description.
• Custom-name the separate branch that will be auto-created by the prompt.

Handling bugs and errors

For bugs and errors, your options include:

• Reporting it by filling out this issue form.
• Follow the steps outlined earlier in the "Editing an existing entry" section.

Conclusion

At this point, you will have committed/pushed your changes and submitted a pull request to be reviewed by either me or one of my colleagues. After we've approved and merged the changes, congratulations! You've just made your first contribution on Codecademy Docs!

I hope this post was help to anyone interested in building the next best documentation resource. I'm excited to have helped build this project and I hope you'll come and help us build it more!

To hear any updates with Docs, go to #CodecademyDocs on Twitter. And please feel free to leave us any feedback about Docs here.