In the very first Programming By Stealth supplemental episode, I interview Dorothy Rendon, the programmer behind the PBS Index. If you haven’t seen it before, it’s an index that Dorothy has created for the Programming By Stealth students to helpt them find key topics in Bart Busschots’s fabulous tutorial shownotes.
We’ll first get a little background on Dorothy and then move on to learning how she used to produce the index, and how her advanced learning in Programming By Stealth allowed her to simplify the process and make it prettier, using JSON, Bootstrap and mustaches. I didn’t want to leave you without something in your Programming By Stealth feed while I’m on vacation and I think you’ll find it a lot of fun.
If you want to chat with Dorothy about the PBS Index, you can find her in the Podfeet slack at podfeet.com/slack under the handle @MacLurker.
10-15 years ago I met a woman named Dorothy Rendon at the gym. We bonded on the ellipticals while watching the soap opera, “All My Children”. As we got to know each other, I discovered that she was a retired programmer. Of course I coerced her into listening to the podcasts. But then when Programming by Stealth started, we had a whole new line of discussion for our workouts, especially since AMC was cancelled.
I’ve asked Dorothy to do a PBS supplemental episode all about the PBS Index and how she’s used what she’s learned in PBS to create and enhance it.
- Before we start talking about the PBS Index, can you give us a little bit of background of your programming experience before starting Programming By Stealth ?
- I’ve been working with computers since I was 17 when it was all batch-processing & punched cards.
- In my first job I started out with automated type-setting systems for newspapers, but, later moved into aerospace, where I designed & wrote software for satellite control ground stations and test systems.
- I love the puzzle of figuring out how to make things work. Although I am retired now, I am having so much fun with PBS. It has upgraded my programming skills while allowing me to avoid all the tiresome tasks of software development like creating requirements, documenting, and supporting users.
- What was the problem you were trying to solve with the PBS Index?
- It was mostly my failing memory. I would think “Bart explained all this before, but where?” Then I’d have to hunt through all the PBS lessons. Very tedious.
- How do you decide what should be in the Index?
- Sometimes I just use Bart’s sub-headers in the show notes. Other times, if I need to look up something not in the index for the week’s challenge, I just add it. It’s all stuff that I think will be useful. Certainly I like to point to where Bart has put the documentation links.
- Fortunately I left the system flexible enough that I can add a link to anywhere, not just the PBS pages.
- I should point out adding a topic is trivially easy. So listeners can feel free to suggest additions if they think I left something out.
- We’re going to get into the big upgrade to the PBS Index in a little bit, but let’s start with your first generation. How did you take notes for what you wanted to include?
- I used MS Word to create requirements and a user guide. This was to help me remember how it all worked. I find it useful to think out how my programs will be used, user inputs & outputs, work flow, before I even write any code.
- A software best practice is to avoid putting the same data in more than one place. That way, if you need to change the data, you only need to change it once. It was clear that there could be multiple topics per PBS lesson & therefore multiple links. So I separated the URLS from the topics.
- I used 2 Excel files. One file was a list of all the PBS lessons, their titles, and URLs. The second Excel file contained all the topics for the index. I used a short text string as a key to connect each topic to the associated PBS lesson data.
- What technologies did you use to convert from Excel to HTML?
- This was before we learned about Mustache. I used Excel to define topics with their related URL. Excel files are easy to create, edit, and sort. Then I wrote a Perl script (my favorite programming language for manipulating text) to read a CSV version of the Excel files and write out an HTML file containing a table with a row for each topic.
- Initially I created a short dummy index page to work out the formatting and data placement.
- On WordPress, I was able to create a web page that Dorothy could erase and replace with her new HTML every time there was a new lesson published by Bart. She only has privileges to that one page (I think)
- One of my great joys is learning just enough to suggest little projects for Dorothy. When we started learning JSON in Programming By Stealth, I thought maybe there was a better way to generate the HTML for the index. This little tickle of Dorothy’s brain is what took us to the new and improved version of the Programming By Stealth.
- Can you talk about the new approach and what technologies are used to generate it now?
- I made the first version of the index over a year ago. I essentially modified a pretty table, using a format Bart provided. That was about all I knew how to do. Later, when I learned how to use Mustaches, it was clear they were perfect for generating the index. And hopefully make for a faster easier update process. I didn’t think about doing updates on the first version; but I wanted to learn from my previous experience. Furthermore, I now had Bootstrap to simplify table creation and text formatting and make a prettier display.
- I started with a new use-once Perl script to convert the two Excel files into a JSON file.
- Then I created a second update Perl script that gets the new PBS lesson data (number, title, URL), and the new topics for that PBS lesson. With that input, the script updates the JSON file.
- I used the CPAN website to find some Perl packages (JSON and DATA::DUMPER) that convert JSON into Perl objects. Once I have a Perl object, it’s easy to insert new data, convert back to JSON, and write to file. Like JavaScript, Perl has all kinds of packages or libraries to extend its capabilities.
- Is it actually easier for you?
- I’m not sure yet. We only just deployed the new version. However, I was able to make an Automator work-flow to guide me through the steps from deciding what topics to include to transferring the updated JSON file and HTML file to podfeet.com. That will greatly simplify the update process and make sure I’m consistent.
- Also, instead of two files to update, now there’s just one. The JSON file gets updated for each new PBS lesson. The HTML file should not have to change once it’s working. Although I will probably tweak it now and then as I learn more.
- On my side, I created a directory on my server and gave Dorothy privileges to write to it. She can upload the new code (if it’s changed) and her JSON file with the new data, all without any intervention from me.
- Your new version is aesthetically much more pleasing – what tools did you use to accomplish that?
- See above. But Bootstrap for the most part.
- The new version of the index has the HTML and JSON files in a directory on podfeet.com, and there’s one line in a WordPress page to make it show up on the website. That one line is an iframe and it’s very clumsy. We talk in the interview asking if there is an easier way.
- I know you won’t be able to leave this be – what do you hope to do in future enhancements?
- Currently I have the entire index in one page. This makes it really nice to use because the browser’s search ability can find the topic you want anywhere in the index. But, the index page is getting pretty long and awkward. And I have no idea how many more lessons Bart will create. At some point I’m going to need to split it into multiple pages, maybe where user selects the size, or add an alphabet selection to jump the user to a specific section. I have no idea how to make that happen. Yet.