Parul Sharma

English 3302
Tom Akbari
Unit 1 Final Draft
1 February 2016
The Importance of Humanizing Technical Documentation
The piece of technical writing I have chosen to analyze is the GitHub documentation,
specifically the article entitled Syncing a Fork. This article can be found under GitHub Help,
which is a directory of help and how-to articles.
I didn't always code. In fact, unlike many people in my major, I didn't start until college.
It just wasn't my passion. I was interested in it and keen on learning, but it didn't keep me up at
night. Part of this means that I wouldnt stay up figuring things out on my own because I enjoyed
it. If there was documentation, I would actually read it. Even after four years of studying
computer science, I still heavily rely on documentation all the time even though I feel more
confident in my problem solving abilities. GitHub, in my opinion, has always had pretty good
documentation. Ive noticed that documentation sometimes gives me anxiety or stress, especially
bad documentation. Turning to documentation for help during a state of confusion, and then
realizing you dont understand or follow the steps is very frustrating. I think this turns people
away from coding.
The documentation, Syncing a Fork describes how to keep your local version of code
up to date with the master version in a very clear and understanding way. Git, a version control
system, helps keep track of revisions of code so you can go back to older versions, and also see
what changes were made in that version. This is especially helpful when multiple people are
working on one project. Version control systems such as Git can be hard to get used to at first.

Sharma 6

There is a lot of new terminology used to describe new concepts. I know first hand that when
you have very little coding experience or knowledge, it can be overwhelming at first and hard to
wrap your head around. This is why GitHub documentation is so important. Studying good
technical documentation is important because good documentation makes it easier for everyone
to understand the concepts. Version control is a very useful skill to learn, since majority of
software projects are a collaborative effort.
Clarity, repetitive patterns, and analogies or words that invoke some sort of imagery are
all important for effective technical documentation that appeals not only to the avid programmer,
but also to beginner programmers. Here is a screen shot of some of the documentation for
'Syncing a Fork' on GitHub.

The bottom button 'contact a human' is of particular interest and catches the eye. They
could have used any other phrase, like 'live chat' or 'help' or 'faq,' but 'human' invokes another

Sharma 6

emotion. In fact, it stands out on the page. You would never expect the word human to appear
in a documentation about or relating to computers. Technical documentation is often very dry
and lacks a lot of emotion. There isn't a lot of emotion required in the language used to describe
how to set up, merge, or fork a branch. It's all very direct. But people who use technology have
emotion. And often, that emotion can be frustration, especially when directions don't make sense
or you follow every single step to the letter and it still doesn't work. Using the word 'human' puts
the user/reader at ease because it shows that whoever wrote the document understands the needs
of the user. They don't just want someone who knows the answer and can give cookie cutter
instructions. That's what computers do. They want someone who understands the frustration and
the human emotion. They want a human.
I also like how certain terms are named in technology. When there is terminology that can
also be used as an analogy to describe the function of something, I remember it better. For
example, in the documentation above, you see words like "push" "checkout" and "master." Each
of these words invoke an image in my mind. The image in my mind is usually a concrete
definition of the word. I then use that concrete imagery and find the analogous technology
function it serves. For example, the word "master" reminds me of "master key." Essentially, this
is what "master" is. The master branch contains the original code and the final version that
everyone should have access to. It should be the most up to date. If you were to make a copy of
the keys for an apartment, you would make a copy of the "master key." In the same way, if you
were to fork your own copy of code, you would fork it from "master." The same way, "checkout"
reminds me of the checkout line at the store. "Push" reminds me of pushing furniture through a
door. These images may seem silly, but they are analogous to what they actually do to code. If
you are new to coding, analogies help in remembering computer science concepts and terms.

Sharma 6

Hence, such simple terms are very crucial and beneficial to understanding complex computer
science concepts. Due to these reasons, the author of the documentation adds a clarity by
including analogies and can appeal to a wider audience, consisting of both proficient and
beginner programmers. One way in which the author can improve the documentation is by
explicability stating the analogies and helpful imagery as I have above.

Code snippets are very helpful in documentation. You can see that the above screenshot
image of the documentation goes above and beyond and even keeps the font and colors
analogous to that of what you would see in the terminal. This subtle visual attention helps to
separate the instructions to what you actually see in the terminal and what you are supposed to
read/see print out and what you are supposed to type. If someone were to explain directions to
you verbally while you look at what is visually written in the terminal, you would not have to
think about this distinction. This is because the visual/verbal distinction is organically there.

Sharma 6

When it is all written documentation, this is a lot trickier. Hence, visually distinct and appealing
code snippets help enhance the clarity of documentation.
Another observation made about the documentation is the structure of the steps. I noticed
that each of the steps is no more than two sentences long. This may have been done on purpose.
The reasoning behind the short sentences and minimal writing reflects that the writer has kept the
reader in mind. The reader is trying to follow along this piece of writing, while also following the
steps. Directions are easier to follow when they are short and to the point. If the following
documentation was written exactly the way it was right now, but formatted as only one
paragraph, it would be harder to follow. As seen below, by visually breaking up the entire flow
into five steps, the tasks of syncing a fork no longer seems overwhelming. It puts the reader at
ease. This is especially nice given their lack of experience and uncomfortableness in a new
situation, which is why they are probably looking at the documentation in the first place.

Sharma 6

The analysis of the above text matches my expectation of the field. Most of the technical
writing developers come across in the computer science industry is very dry, direct, and to the
point. The documentation above matches with what I encountered in my co-op experience.
However, GitHub went above and beyond with the code snippets and font visuals to differentiate
code from instructions. Next time I am asked to write documentation at work, I will make more
of an effort to include code samples and style them differently from the rest of the directions so
that they visually stand out like they do in the above documentation. My current writing skills,
however, do not match the present document. I could work on being a more concise writer. The
above documentation is very dense, and explains a lot in a very few amount of words. This is a
skill I would like to gain.

Sharma 6

Reference
1. Syncing a Fork[Internet]. Sciences: CSE in-text citations; no date [cited 25 January 2016].
Available from: https://help.github.com/articles/syncing-a-fork/