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.

Pet Containers

Pet Containers
On git hub hackoregon/data-science-pet-containers are very useful Docker containers. Tools included are PostgreSQL, PostGIS, Anaconda and Rstudio. Add data and you are all set for exploring and developing. If you have any problems file an issue on git-hub. I am looking for what is missing from the directions.

large white dog
curious white dog

Technically Wrong

Written by Sara Wachter-Boettcher, Technically Wrong is the best popular press book written about miss-classification and algorithms.

The chapters in the book cover common issues and problems that should not be happening.

From Chapter 10, Technically Dangerous

page 196

Software is designed and coded by people not representing the general population …” The narrower those people’s perspective’s are, the more they design and code like themselves and shrug off any responsibility for outcome, the more inequality, insensitivity and hate can thrive ”

People die from classification errors.

Small choices matter.