Updating a whole department of notes because Apple slightly changed the meaning of things

ctietze

This week I've ran into an annoyance more often than before:

Apple changed some of their programming libraries for user interfaces (SwiftUI & Observation framework) so that you'd wire things slightly different, but with a 30% overlap in terms. My notes from the time prior to that change sound like they still apply, but there's a chance that the minute details are outdated, or even so wrong that applying the tips would produce worse, not better apps.

Essentially, every note up to and including 2023 on the topic is at the risk of being outdated.

Usually, when tech I have used and researched is outdated, it merely becomes irrelevant. The notes perused less and less often. That's a normal process in the ways of language, library, and system evolution.

But this time, it's still the very same, relevant topic, but the meaning has shifted slightly. In some cases.

I can search for (2023 OR 2022 OR 2021 OR 2020) AND (swiftui OR observation) in The Archive and mark all 198 matches as ##stale or something like that, then when I encounter these later, I know I need to be careful and update or ignore the notes. That's a shotgun approach that will mark more notes stale than needed, because some tips are still relevant. I don't see myself going through all of these

Or I copy links to all these matches into a buffer note that's a to-do list to update these notes. Then I don't need to touch all the existing notes. And I have an overview that I can work in, like: group some of these old notes into clusters, essentially create "piles", so I can research updates in bulk and make the task more manageable. This will not mark notes stale that don't have any stale information, and it's an easier working surface. It will not warn me about a note being stale when I look at it, though.

Maybe I need to combine both.

Have you encountered a situation like this before? Anything you regret doing that I should definitely avoid?

Andy

No, I haven't been in a situation like this before. But since we're already at over 50 views of this post with no comment, I'll throw in this suggestion: Perhaps you need some kind of explicit software version tag for software-related notes? (I think of how online software documention is versioned, e.g., in Sphinx.)

zettelsan

My notes do not include an extensive collection of technical snippets that change that fast, so I cannot say that I have encountered the exact situation.

But over the years, I have kept some Linux installation/configuration notes for incrementally updated systems that do not change drastically but modestly enough that I created a new note. In those cases, using slightly different document titles sufficed (e.g., "How to install Debian Jessie on ThinkPad" vs. "How to install Debian Stretch on ThinkPad").

If I were in need to keep separate notes for different versions like @ctietze in the OP, I would agree with @Andy above and would use a version tag for mostly duplicate notes in my current note-taking system.

The ability to version documents, not as in Git but as in cloud object storage, might look fancy and useful, but it must be difficult to main such a system. What if a need arises that you want to pull notes for all the legacy versions at once? Tagging seems simple and effective, though duplication might not sounds ideal.

zettelsan

@zettelsan said:
The ability to version documents, not as in Git but as in cloud object storage, might look fancy and useful, but it must be difficult to main such a system. What if a need arises that you want to pull notes for all the legacy versions at once?

I'm responding to myself, but Git-style version control may actually work well if the part of your Zettelkasten storing the software-version sensitive notes are in a separate version controlled repository in its entirety. Then you can Git-tag a commit with a software version and keep overwriting existing notes with new info. You can then revert to a previous version by Git revert, if ever necessary.

This workflow may work well if you use a version control system and don't care about ability to see notes for different versions side-by-side. I might consider this for myself for notes that I expect to have the issue in the original post.

ctietze

@zettelsa Both Your "Debian Jessie" example and @Andy's suggestion for versioning are great, because they show what Apple forgot: to annotate their documentation so that you could find versioned information. Under the hood, people know "Swift 6.1" and "SwiftUI 5" and so on, but it neither shows anywhere, nor is there a way to go back in time (to "SwiftUI 3", say). Instead, it's all just mixed together.

Andy

@ctietze said:

what Apple forgot: to annotate their documentation so that you could find versioned information. Under the hood, people know "Swift 6.1" and "SwiftUI 5" and so on, but it neither shows anywhere, nor is there a way to go back in time (to "SwiftUI 3", say). Instead, it's all just mixed together.

I've been learning about Nix and NixOS recently, so my first thought upon reading this comment is that Apple's approach to Swift documentation sounds like the macOS approach to application management in general: quite disorganized compared to NixOS, and, more specifically, impossible to easily roll back to a previous version/configuration. I'm reminded of a response to a question in a Linux subreddit, "Why doesn't everyone use appimages instead of .deb, .rpm [or .nix] or other native binary system?" To which someone responded, "Short answer: If I wanted to run macOS, I'd do that instead." (To be clear, I love macOS, and I use a Unix package manager with it, but this person is not wrong.)