Tag Archives: documentation

Documentation Needed

Dark Brown Chocolate cups cakes with white powdered sugar sprinkled on cupcakes
Chocolate cup cakes

I write cooking recipes for publication. Documentation is a lot like writing recipes. Recipes are for all types of cooks, beginners and experts. Most of the documentation I find is sparse, lacking details, written for the person who wrote the code. It is hard to write directions for people who don’t know how to use or do the coding. I have been trying to expand the documentation for some Docker containers and I can’t find a new user that can tell me what is missing. I hear everything is find from experts.

Suggestions for requirements for documentation from recipes submission requirements.

Title, something instead of documentation.

Tell us about your recipe. Needs to be a little more than it is a Docker container.

Ingredients. Let people know what is needed. Software, libraries, how much memory needed. Give people an idea if they even can do the task with what system they have. Do not send people to the grocery store for a missing ingredient or to borrow a cup of sugar from a neighbor. This is really important for when people come to a half day workshop only to find out they can’t participate.

Prep method, for recipes what is needed is stove top, oven, grill, blender. What are we doing? Baking? Spinning up a web server, database. Be clearer are we frying or blending?

After clearly stating what we are doing, write out the directions. Include prep and cook time. For example it takes three hours to code this. Build time is half a day. Recipes state what occasion Holiday they are for. Also what category. Github tags make this easy, use them. Course Breakfast, lunch, Dinner. Quantity served. From these ideas Think the documentation thru to more useful documentation. Stack Overflow should not be your only documentation.

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.