Narcissus Looks Back

Introduction

Not knowing what he sees, he adores the sight;
That false face fools and fuels his delight.
You simple boy, why strive in vain to catch
A fleeting image? What you see is nowhere;
And what you love—but turn away—you lose!

In Ovid’s Metamorphoses, a young hunter named Narcissus sees his reflection in a pool of water and falls in love with it. He can’t look away. He stares at the pool in longing till he withers away, dies, and transforms into a flower.1

  • 1 Ovid. Metamorphoses. Translated by A. D. Melville. 1986.

    • From Narcissus we get “narcissism,” which is generally used to refer to excessive self-centeredness or selfishness. Narcissus seems an appropriate mascot for this essay. For this is an self-indulgent essay about what I’ve done over GSOC 2023.

    Don’t misunderstand. I love navel-gazing. This essay is also part of GSOC’s work product submission requirement, so here we are. Enjoy.2

  • 2 Or don’t. I’m not your boss.

    • What I Did

    Reference Website

    My principal contribution was the construction of the animint2 reference website.3 I’m pretty proud of it. I wrote a quick start guide to introduce people to animint2, organized and summarized animint2’s many functions, re-wrote the README, and made other little changes to make the website comfortable and usable.

  • 3 See the pull request here.

    • Making the website was exhausting in parts, but broadly it was a satisfying experience. I love making websites. I love HTML and CSS—though I actually wrote very little HTML during this time, since the website was generated with pkgdown. Most of the HTML I wrote can be found in the quick start guide, intertwined with the Markdown that composes much of the document. This sacrifice of aesthetics was an unfortunate necessity. By themselves, Markdown and pkgdown just don’t have the power to do what I need.

    The most technically challenging part of website-building was designing the code annotations and making them appear in the quick start guide.4 Recall that pkgdown generates the website, which leaves me limited control over the HTML, which limited my options for code annotations. My workaround was to use R comments and then use CSS to make the comments appear like annotations. I also had to do a bit of CSS trickery to make ordered list markers appear like the code annotations.

  • 4 Credit to Toby for the code annotation idea. Thank you, Toby!

    • TODOs to Datasets

    Honestly? This barely counts as a contribution. I’m just including it here for completeness. I noticed that sources and codebooks were missing from some of the dataset files. I documented all the files that were missing information. Then I added a bunch of TODO strings to those aforementioned files.5

  • 5 See the pull request here.

    • GitHub Issues

    I opened up a bunch of GitHub issues, thereby making work for future contributors of animint2. I’m creating jobs!6 Issues that are still open:

  • 6 Kidding. 😛

    • Issue 90: Observations on a Scrolling Bug. I noticed that pages with animated animints scroll upward on Firefox.
    • Issue 106: Animints Don’t Render Alt Text. I noticed that {r fig.alt="foobar"} worked for ggplots, but not for animints.

    Failures

    Early on, I was tasked with closing issue 89. I failed. It’s about removing animint2’s dependency on the maptools package.

    I also never solved issue 96, which I opened. It’s about \(\LaTeX\) throwing up errors when I use build.sh. As far as I know, this issue has only ever affected me.

    What’s Missing

    This official title of this project is “The animint2 Documentation and Bug Fix Project.” I’ve only really done the former and have fixed zero bugs that were not of my own making.

    During GSOC, I failed to make animint2 a hexagon badge. I was planning on designing one near the end, but I ran out of time. This is the only part of the website that I’d say is truly missing.

    Something that I would’ve liked to do is automate the website rendering via GitHub Actions. Unfortunately, I don’t know how GitHub Actions works, and I didn’t have enough time to both learn about it and implement it.

    What I Learned

    Theory-Building is Right

    When I first read Peter Naur’s paper on programming as theory-building, I thought it was a neat idea.7 My experience over GSOC has corroborated the theory, and I’ve come to believe it.

  • 7 P. Naur. Programming as theory building. Microprocessing and Microprogramming. 1985.

    • See: I built the animint2 reference website over a period of about three months. I know it intimately. I know what every line of _pkgdown.yml and pkgdown/extra.css do. I know what I need to do to build the site right, and how to debug it when things go wrong. I’ve built up a wealth of tacit knowledge—in Naur’s words, I’ve developed a theory.

    I’ve tried my best to document everything. However, according to Naur, that’s not enough. This tacit knowledge cannot be communicated in writing. Nor is it present in the source code. It can only be communicated, indirectly, via mentorship.

    HTML and CSS Rock

    I’ve also continued my path of becoming a curmudgeon with a distaste for frameworks that write HTML and CSS for me.

    Don’t misunderstand me. Within bounds, these frameworks are wonderful and can save effort and time.8 I’m glad pkgdown exists—it would be a real pain if I had to write the HTML for every single function. pandoc saves me an enormous amount of time and effort.

  • 8 This website was built using Quarto, which spared me the effort of manually constructing HTML sidenotes.

    • But these abstractions also limit my control over how websites appear. Markdown was built for an older iteration of HTML, and it mixes semantics and appearances. When I italicize, it can’t know if I mean <em>, <i>, or <cite>. I also have concerns about accessibility. Problems with screenreader accessibility, for example, must be addressed via HTML—which I have limited control over.

    Watch for Typos

    Finally, I’ve learned that typos cause a surprisingly large number of problems. If things aren’t working right, I ought to read my code again—carefully and slowly. There just might be a missing quotation mark, whitespace, or bracket causing the issue.

    Thank You

    Thank you to Toby Hocking for accepting me as your mentee for GSOC 2023. Thank you also for mentoring me. I hope my work has repaid your confidence and your effort. I appreciate the independence I had to do this work, and I also liked the asynchronous communication structure we had in place. You were a great mentor to this cat-obsessed weirdo.9

  • 9 In fact, you are arguably my first computer anything instructor.

    • Thank you to Yufan Fei for your advice and perspective. Between us, you are the more experienced, and you did this last year. I appreciate that you emailed me and said we ought to communicate. I’m thankful that we both did GSOC 2023 together.

    Thank you to Faizan Khan for your help, especially at the beginning. I didn’t get to know you very well, but perhaps that will change in the future.

    Closing Thoughts

    In Seizing the Bits of Production, JeanHeyd Meneide summarizes his experience during GSOC 2019. In short: he did amazing work and met all his goals.

    Being a less impressive person, I haven’t. But I think I’ve done good work regardless. And you know what? That’s good enough for me.