Troubleshooting

Monday, 10 July 2017

This session will be primarily dedicated to helping you work out kinks and wrinkles in the process of getting your site online and completing the second assignment. If you are already very far along, then this is an opportunity for you to finish your work.

Looking for Trouble

In addition to completing your site and the assignment at hand, we will start looking at ways that you can teach yourself how to fix problems that happen. Being a good beginner is about figuring out how to figure things out.Denning, Peter J. “The Beginner’s Creed.” Communications of the ACM 60, no. 7 (June 26, 2017): 30–31. https://dx.doi.org/10.1145/3097352 You will always run into issues, no matter what you are working on. This will never stop.

At that point, you have two options:

Wait for someone to help you.
Figure it out on your own.

Guess which one goes further in the course of your academic and work lives.

Rules v. Conventions

There is a hierarchy of rules that you need to be aware of when troubleshooting issues.

Rules - explicit conditions without which something will not work (syntax of commands or markup, etc.). Failure to comply with these will result in code not being able to run/compile.
Conventions - common ways of doing things that are agreeable to others (tabs v. spaces, heirarchical indents, etc.). Failure to comply with these will not produce broken code, but might irritate your colleagues.
Customs - practices that a lot of people do, but for which there exist no specified guidelines.
"Best" practices - recommendations from expert or more experienced users/developers to improve performance, ease of use, usability, etc. These vary wildly.

Sources of information are myriad

It is really difficult to recommend places to get help with troubleshooting online. This is not because they are so few, but because they are so many.

The best approach is to actually see what information you can get directly from the error interaction and then move on from there.

Read the error and try to understand it in plain language. That may work some of the time.

Some error systems give VERY helpful errors that include suggestions for ways to fix what has gone wrong. Git is like this. If you have a git error, most of the time, it will tell you what has gone wrong and how you can fix it. Usually you just have to read it and do what it says.

Sometimes error messages will be more obtuse: this is a legitimate and well-known fact.

If you catch an error that doesn't make sense to you, try at the very least to figure out what it means or to what it is referring.

Google it

Take this error, for example:

error: Entry '<fileName>' would be overwritten by merge. Cannot merge. (Changes in staging area)

This is not particularly helpful. I could pore over the git documentation for this, or I could take a more reasonable path and Google it.

As you can see, there is a fair amount of information immediately available that will help you cirvumvent that error.

Take this approach first and keep these things in mind:

Be careful: not all information is good.
Learn to spot the difference.
READ.

Stack Overflow is generally a useful resource for recovering from errors. It is well curated and lots of people use it to figure things out.

For Next Time

Next time we will start working on manipulating and formatting text. ⊕Wiens, John A. “Word Processing versus Writing.” The Auk 100 (1983): 758. https://sora.unm.edu/sites/default/files/journals/auk/v100n03/p0758-p0758.pdf.

Caleb McDaniel, W. “Why (and How) I Wrote My Academic Book in Plain Text | W. Caleb McDaniel.” Last modified September 28, 2012. http://wcm1.web.rice.edu/my-academic-book-in-plain-text.html.

Stross, Charlie. “Why Microsoft Word Must Die.” Charlie’s Diary. Last modified October 12, 2013. http://www.antipope.org/charlie/blog-static/2013/10/why-microsoft-word-must-die.html.

To prepare for this philosophically, I would like you to read a few blog posts and a very short article.

The first is a short article from about the difference between word processing and writing from the earliest days word processors.

The blog posts are about the relative merits of giving up word processors altogether and using plaintext the way we have been in this class.