How You Can Improve Open Source Documentation


I gave a talk at the end of the Ascend Project about my troubles with Open Source Documentation. I called the talk Cookie Crumbs.  Maybe I should of named it after the three Bears and Goldilocks.  Some documentation is too little, some too much. Here is what you can do to make it just right. I am assuming that you have a git hub account and use git.

Find a project repository on git hub . Read the documentation.

Fork the repo to your git hub account.

In a terminal window on your own computer make a folder for the cloned repo.

mkdir name_of_folder

cd into that folder

cd name_of_folder

In that directory at command prompt type in the text from SSH clone url box on the forked repository page.

git clone your_fork_SSH_clone_url_code

Next so that you can push code back to git hub you want to check out a branch. Give the branch the same name as the folder.

git checkout -b name_ of_branch

This command will also switch branches, an extra bonus.

This command makes your branch the master.

git branch -D master

Open the documentation that came with the clone repo in a text editor. Documentation often ends in .md for markdown. You want to use git hub flavored markdown.

Write , code whatever you think is necessary to fix the documentation. It can be as little as spelling and grammar errors, localization or as big as a fancy new tutorial.  When you are finished make sure you save the file into the folder for the checked out branch.

Now you are ready to push the code back to git hub.

Before you push check git status and commit anything that needs committing.

git status

git commit -m”message”

git push -u origin name_of_branch

Go to your forked repository on git hub and issue a pull request for the pushed committed code back to the original repository.  Hopefully your pull request is accepted.  If not the documentation is still in your forked repository ready to be found and used by someone.