Whatever happened to …

… internal documentation?

On a typical day, it’s not uncommon to have to update applications or operating systems or drivers or whatever on your computer.

it’s a fact of life and good computer users who want their software to be running the latest and safest will do it regularly.

But, think of the programmer that works to make these updates available.

Do they turn on their computer and look at a bunch of code in whatever language the update is written in and read everything from top to bottom and understand every step, every procedure, the purpose of every variable, etc. every time they have to update the code?  What if you’re on a team and there are a number of other programmers?  How do you know what your colleagues are doing?  

It would be a pretty tedious job if they did.  And, what if the original developer and holder of the information has left the organization?  Does the subsequent author have to learn from scratch?

Of course not.  Crucial to this is internal (and external) documentation of the program.  A good piece of software is like a good story.  It’s well written, documented, and described.  Check these out.



So, every programming language has the ability to do this?

Not so quick.

Take a look at one of the more popular first coding platforms – Scratch.  It is very powerful and designed to make things easier for the developer.  Yes, students are developers in their own right and at their own level.  The Scratch website allows for the resharing and repurposing of code and good contributors will have a good description of how the code works.  But, internally?  

What programmers refer to documentation is an entire different story.  Pick up someone else’s code or revisit something that you’ve written in the past and you’ve got to read it at times like you’re reading it for the first time.  It’s so inefficient and inconsistent with the principles of good coding techniques.

And yet, we promote this with the intent of getting students involved in coding for their first language.  How many times do we hear that Canada doesn’t have enough programmers so we need to develop them now?  Scratch and similar languages are the launching pad and yet it doesn’t support the internal documentation that will be required later should these programmers decide to take it seriously.

What are your thoughts for a Sunday morning?

  • How do you have your students document their coding and their thinking?
  • Have you ever revisited code of your own and have no idea how it was constructed?
  • What are the techniques that the beginning coder should have to guarantee success?
  • At what point do students need to learn about internal documentation if their first language doesn’t support it?
  • Is it possible to “over document” a piece of code?

Please share your thoughts in the comments below.

Check out the entire collection of Sunday morning memories here. And, if you’re so inclined, through a suggestion in the Padlet.



OTR Links 04/30/2017

Posted from Diigo. The rest of my favorite links are here.

Custom words

If one of the goals in life is to reduce work, then it only makes sense to do things to help the cause.

Every time I get a new word processor or any other piece of software that includes a spell check, I’ll add certain words so that they don’t get flagged as incorrect or, even worse, changed to something else via auto-correct.  Previously, I had shared how to turn on auto-correction on a Chromebook.  I called the post “The best setting ever“.

It’s still a great feature but needs a little tweaking.  This Chromebook setting is really unique in that it applies to everything that you might want to run on the computer.  So, I went about adding my custom words.  There are some technical terms that I immediately add, then it’s on to family members with unusual names, and then there are the locations.  

A typical starting point for this is a geographic wandering around Essex County.  These are the locations that I probably use the most.

To add them to the dictionary, it’s just a matter of choosing the keyboard settings and then the Configure button to get to the settings for that keyboard.  

Editing the dictionary settings takes you to your custom collection.

Just go ahead and add your custom words.  

It may not make you the letter perfect writer you aspire to be, but it’ll help you reduce those squiggly lines.

Nobody likes squiggly lines.

Aw, man …  I forgot one…

OTR Links 04/29/2017

Posted from Diigo. The rest of my favorite links are here.

This Week in Ontario Edublogs

Yay!  It’s the weekend.  I hope that you have great plans.  Here’s some reading from Ontario Edubloggers to help you get through Friday and out the door.

What is Deep Learning Anyway?

The CanConnect conference started on Wednesday and Peter Skillen sent out this message with its hashtag to remind folks that we just didn’t start this current coding fad last Tuesday.

Peter has a set of shoulders that many of us have stood on.  I know that ECOO has a collection of lifetime members; certainly Peter should be considered for nominations if they are looking for names.

In a recent talk on the Learning Exchange, Peter shared many of his thoughts.  People would be well advised to click through and watch it a couple of times.  That latest speaker that extolls the virtues of programming in Scratch or claiming that Computational Thinking is something new isn’t exactly a ground breaker.  People like Peter have coded with kids for years, not to draw some fancy diagram but to get at the deeper thinking and problem solving that is possible.

His talk is embedded into this post.

Growing Up Royan 1: Delivery

This has the possibilities of being on of the better blog post series that you’ll read.  Royan Lee is, through text and drawing, going to attempt to get us to understand the inner Royan.

This first post is a great story that starts at birth and with his name.  To help think along with Royan, he provides some prompts.

There’s some great thinking prompted here.

One more question would be – would Royan’s parents have made the same decision today as they did back then?  Have attitudes changed over time?

Continuing the Conversations on Cell Phones

This is the question that just won’t go away.  This time, Melanie White takes it on with her Grade 9 students.

In her classroom, she’s doing her own bit of action research and it involved the purchase of Yondrs.  (See her post for a picture)

Faced with a classroom task, the students, with their devices tucked into the Yondrs work at it and Melanie collects some of their thoughts afterwards.  They may not be what you expect them to be.

From the activity, she describes three lessons that she’s learned.  They’re interesting but doesn’t give to me a definitive answer.

But, in the middle was this gem — “me to feel that often grade 9 students don’t see their cell phones as “powerful computers””  It seems to me that, if this is truly the case, then the use of them in the classroom will never be the game changer that people purport them to be.

What needs to be done to lay the groundwork for students to reach that level of awareness?

Should we still have School Boards? A Public Challenge

Paul McGuire points us to an interesting article in the Globe and Mail.  Around here, the discussion of Catholic and Public School Boards covering the same geographic area reaches fever pitch every time the local newspaper “exposes” those who are on the Sunshine List every spring.  “Why do we need to have duplicate structures in place when one would do?”  How many trustee positions have more than one candidate?

Paul’s observations are interesting.  Typically, you hear that from an employee of a Public board made in reference to Catholic education.  But, Paul is from the Catholic side of things.

Stephen Hurley and I were discussing this post on voicED radio.

However, the proposal in the article doesn’t head in this direction.  It calls for the elimination of all school boards.  The article has points and observations guaranteed to make you think.  In our conversation, Stephen and I got talking dollars and cents.  Paul was at the keyboard…

He’s correct with respect to the article but anything political inevitably ends up talking about money.

I don’t think we have to worry about anything to do with this any time soon.  This would require rethinking everything that we know about the governance of education.  If we took that one piece out of the puzzle, would the puzzle tumble?


I ended up with a big gap between expectation and reality with this post from Tamsin Cobb on the TESL Ontario Blog.

I expected to read about student volunteerism in a second language setting but, instead, got some insight to how the content for the TESL Ontario Blog is created.  When you sit in your study writing for your own blog, you take on all the roles.  I do have people like Lisa Noble and Sheila Stewart checking to see if I a word out.  But, for the most part, it’s just me.

Tamsin lists the tasks:

Our bloggers and administrators give hour after hour of their personal time to write posts, edit posts, publish posts, work out technical glitches, and ensure everything is of high-quality and runs on schedule.

There really are a lot of tasks that a blogger performs including doing all the research before even getting started.

I wonder if student bloggers feel the same way?

Creating a Test with Students


Isn’t that what teachers are paid for?  Don’t they take all those courses and workshops on assessment and evaluation to become proficient in this task?

Of course, and it won’t change any time soon.  But a little experiment from Colleen Rose will get you thinking and maybe taking a risk in your own classroom.

She taught a unit dealing with the Renaissance and had her students make up questions (along with answers) for a unit test.  It’s an interesting approach, especially when she pulled them all together for all in the class to see.

I really enjoyed the observations that she made about students wondering about the type of question to be asked.  It reminded me of working with colleagues on a common exam.  For students to have that conversation really shows a great deal of maturity.

I think an interesting activity would be to compare the test that she might normally have given with the one that the students created.

  • Is the test about the teaching or is it about the learning?
  • Who created each?
  • Which would give the better result?

OCTE Annual Conference 2017

Peter Beens sends us a reminder that the OCTE (Ontario Council for Technology Education) conference is fast approaching for those who are interested.  In fact, the early bird registration ends today!

You can download and check out the entire conference program from here. (PDF file)

I hope that these blogs give you some great reading for this Friday leading into the weekend.  

Enjoy each by clicking through to the original and drop the authors a comment.

If you’re free on Wednesday mornings at 9:15, join Stephen Hurley and me on voicED radio as a few of the blog posts that ultimately end up here serve as a launching point for some discussion.  The show is repeated throughout the week at different time slots and they’ve all been recorded and served up “on demand” from here.  Live is always more fun; you can hear all the bloopers before Stephen edits them out.  We had a crazy time this week with him wrestling with hotel WIFI.

Until next week…