Last week, I worked on the IPC144 modernization project.
What is IPC144?
IPC144 is a course taught at Faculty of Software Development and Data Science in Seneca College, primarily given to beginners at programming through the C programming language.
Most of the course work notes are publicly shared by a website. It has been noted that the previous design and feel of the website was outdated, and thus a modernization effort was brought forward.
How are we modernizing it?
All of the pages are written into Markdown files, and then latter processed with docusaurus to serve over the wire. Although the main purpose of docusaurus is to write documentation along your programming project, the layout is general-purpose enough that we decided to use it for the IPC144 course notes.
Although most of the translation from the old notes to the new design was automated by a program to generate Markdown files, there were some small details to clear out before it was time for the new students to use it.
Some issues were things like typographical errors, improving semantics by providing annotations with proper graphics (by using admonitions), improving the Markdown syntax used, among other things.
My contribution
My main contribution was auditing the pointers page. Here you can see the issue that I opened for this particular page. Most of the work was related to the checkbox list that the issue shows. There were some details that I have yet to figure out (how to create a dark theme version of an image's pallete, for example!), but overall, I managed to complete several tasks.
The resulting work culminated in the following PR.
Some lessons learned
While I did zero coding in this PR, I feel that I learned a few things regarding problem organization.
A big one I would like to mention is the discovering process for a problem. There were some tasks in the issue that were more involved the more I thought about them. One, for example, was improving the tables that appeared in the page so that they do not use raw HTMl markup. While I was trying to solve that particular task, I asked myself things like "this table's layout is too complex for regular Markdown!" when working with the walkthrough tables (a table that shows the values of the variables in the code by stepping through the code line by line), and "Could we improve and simplify the design?" Thus, I ended up opening an issue to spark more discussion and suggestions for improving the design of the walkthrough tables.
The big lesson is: if you find out that a problem is more involved than you expected, file an issue and leave it for later! Your PR should focus on a single unit of work so that it is easier for everybody to review and evaluate. If your PR makes too many changes because it focused on too many things (fix this bug, add this feature, refactor this class), then it will be ignored in the best case, and on average it will be rejected due to a lack of focus.
Top comments (0)