By Mary Word
(Relearn what I did—the importance of commenting your own work. Also, big cheers for debug.)
If you have ever done programming, or taken a programming course, you have been told to comment your code. One of the best ways to write code is by writing the comments first – pseudocode, if you will. I have worked with programmers who thought that it wasn’t macho to write comments. (Cue that old movie quote – “Comments? I don’ need no stinkin’ comments.”) They thought that the ultimate in coding was to make it run in as few (and as obscure) lines of code as possible. They not only didn’t care that we worked in teams and other people had to work on their code, but they also felt that the harder someone else had to work to figure it out the better. Then they ‘won’.
Well, guess what. You can be that person to yourself. It is surprising how much you can forget about the details of a complex bit of design on an interactive page. It is likely that you will have to go back and make changes or reuse pages you have made, sometimes a year or more later. It can be like seeing something for the first time.
When I went into the code – I will call it code, although in Lectora it is the Title Explorer, an organized view of all of your objects and actions on a page – I expanded all of the groups and scrolled up and down through them. I was thinking, “Wow, there is a lot on this page.” Here is a piece of it with one of the groups expanded.
All of this is before I even get to any of the main content groups. It is all actions. Something to notice here: use meaningful names for both the action objects and the groups. Even the ones using numbers match up with synchronized events in the audio narration. This is one of the most important things you can do, and in a tool like this that is not straight code, it can serve as your comments.
I also left actual comments, instructions to my future self, or to whatever poor developer might have to work on this after me. Lectora has a Notes function, which makes virtual sticky notes you can leave on a page that are only visible to other developers. I used a pretty substantial one on this page, and was extremely glad I did! I had some general notes about naming and ordering, and that there were over a hundred actions, 5 audio files, over 50 objects, and multiple synched audio events, all of which were interdependent. The note reminded me where some of the actions were hidden, whether inside questions or in the conditional branch of an if-then-else statement. They were invaluable—and even with all of this information it took me hours and the use of the debug function to figure it out step-by-step before I was able to confidently explain it to my audience.
Debug is a great help. It lets you print out a running list of every action and what it acts upon. I could use it to follow exactly how the page ran, and annotated it to explain what was happening. I included this annotated debug document as a resource in my presentation file. Here is a little piece of it:
Although I made this annotated log after the fact for the presentation, I used debug repeatedly when developing the lesson initially. I tested the core functionality over and over until it ran without errors dependably, and I could use it as a repeatable code segment for multiple pages with similar interactions. I also used action groups to initialize the variables which changed on each page, so the setup could be done up front and make it easier to reuse.
Just to give you an idea of developing and testing a complicated interaction, this is a piece of a Lectora file I used to build one, page by page. I would get one part working, copy the page, then work on the next bit. This gave me versions to go back to if something broke. You can also see that I used descriptive text on the page and feedback text to easily let me know if something worked or didn’t. The small amount of time you take to set things like this up saves you so much more time in the end.
Next time: Anatomy of a Presentation, Continued
Contact our Learning Developers
Need to discuss developing e-learning? Creating curriculum for classroom training? Auditing and remediating e-learning for accessibility? Our learning developers would be glad to help.