I often write technical documentation and readme files for work that I’m doing. I often spend as much time, if not more, writing these documents as I spend doing the work. For example, take a look at the HiddenPowershell project that I recently published publically.

There are two files in that GitHub repository. One (README.md) is the documentation page, and the other (HiddenPowershell.vbs) is the actual program. I don’t actually want you to read the README.md file. Just look at the length of it. If you download it and look at it in an editor you would see that it’s 106 lines (74 sloc) of text; albeit specially formatted text. Now, take a look at the HiddenPowershell.vbs file. It is 46 lines (36 sloc) long. Yes, my documentation is about three times longer than my actual code. That doesn’t include the helper blog article that I created for additional information; linked to it from the README.md. It’s 210 lines (149 sloc) long. As I said, I’m used to doing a lot of additional work besides just the real work.

Thoughts on Instructional Design

All I’ve completed so far is the initial design document, and I must say that it is about as monotonous of work as I have ever done. I’m not saying it’s not important. However, it is very tedious. I do enjoy the fact that it is a very firm outline of what I need and expect from the training that I am planning. However, inside the document itself, there is quite a bit of mundane repetition. I felt like I was just checking things off the list as I was writing the document to completion.

For example, the learning activties and the timeline sections had almost identical information. I felt like they could have been combined into one section. As a matter of fact, simply copied the learning activties section and pasted it into the timeline section. I then tweaked a few things; such as adding times and a description.

Overall, I think it’s a good exercise to encourage deep thoughts on a topic. However, I don’t know how practical this is a framework or template for future endeavors. I would consolidate some of the repetitive pieces and streamline it a bit. I’m anxious to see what my peer says about my design document though. Maybe I have completely missed the mark.

References

• (2015, February 12). Deep Thoughts by Jack Handy [Digital image]. Retrieved June 20, 2018, from https://www.vanityfair.com/hollywood/2015/02/saturday-night-live-app