How I Refactor Notes in Obsidian  ## Metadata - Author: [[Nicole van der Hoeven]] - Full Title: How I Refactor Notes in Obsidian - Category: #articles - Document Note: --- tags: - #obsidian - #pkm - #notetaking Author: Merlin AI Source: YouTube / [How I refactor notes in Obsidian](https://www.youtube.com/watch?v=J8-1eOzQ438) Reference: Transcript (00:00–21:57) date created: 2025-08-22 18:30 --- # Title: How I Refactor Notes in Obsidian ## Table of Contents: - [📝 Summary](#-summary) - [📖 Main Content](#-main-content) - [🗒️ Notes](#️-notes) - [📖 References](#-references) - [🗣️ Paraphrase](#-paraphrase) - [📰 Newsletter](#-newsletter) - [✅ Action Items](#-action-items) - [🧪 Hypotheses](#-hypotheses) - [📊 Methodology](#-methodology) - [❓ Questions](#-questions) - [🔮 Future Research](#-future-research) - [💡 Implications](#-implications) - [🧠 Learning Styles Assessment](#-learning-styles-assessment) - [📊 Accessibility Assessment](#-accessibility-assessment) - [🌍 DEIB Assessment](#-deib-diversity-equity-inclusion-and-belonging-assessment) - [✅ Logical Validity](#-logical-validity) - [🔍 DARVO Analysis](#-darvo-analysis) - [🔍 SEO Evaluation](#-seo-evaluation) - [🎯 Conclusion](#-conclusion) --- ## 📝 Summary: The video reframes note-taking in Obsidian through the lens of programming "refactoring." Instead of static information dumps, notes should evolve continuously to reflect current understanding. The process involves inventorying existing notes, restructuring hierarchies, categorizing content, fleshing out details, and modularizing into smaller atomic notes. Tools like Obsidian plugins (Quick Switcher, Strange New Worlds, Excalibur, Note Refactor) support this workflow. Ultimately, refactoring transforms raw notes into a usable, dynamic personal knowledge management system (PKM). --- ## 📖 Main Content: The video compares coding and writing as parallel processes: both distill thought into sharable structures. Refactoring notes ensures they remain meaningful, usable, and aligned with evolving knowledge. The process is demonstrated on a "Monitoring" note, which is expanded to include back-end vs. front-end monitoring, links to observability, instrumentation, and telemetry. Metadata is leveraged to define parent/child relationships, while modularization prevents bloat and improves long-term maintainability. The key principle: effective note-taking is not about quantity, but about cultivating a **continuous knowledge system** that reflects and grows with the learner's understanding. --- ### 🗒️ Notes - [00:01](https://www.youtube.com/watch?v=J8-1eOzQ438&t=1) **Code refactoring analogy** - Writing and coding both abstract and share ideas. - Refactoring = simplifying structure without altering meaning. - [02:20](https://www.youtube.com/watch?v=J8-1eOzQ438&t=140) **Inventorying notes** - Quick Switcher and search help locate related notes. - Plugins like *Strange New Worlds* reveal networked connections. - [04:48](https://www.youtube.com/watch?v=J8-1eOzQ438&t=288) **Structural focus** - Refactoring is usually about hierarchy, not semantics. - Excalibur plugin visualizes relationships between notes. - [07:15](https://www.youtube.com/watch?v=J8-1eOzQ438&t=435) **Strengthening conceptual links** - Observability ↔ Monitoring ↔ Instrumentation. - Metadata fields define parent/child structures. - [09:42](https://www.youtube.com/watch?v=J8-1eOzQ438&t=582) **Restructuring content** - Original categories weak; reorganized into "Why," "Types," and "Approaches." - Clearer separation of collection vs. aggregation methods. - [12:23](https://www.youtube.com/watch?v=J8-1eOzQ438&t=743) **Modularization** - Notes split into smaller units (e.g., "Reasons for Monitoring"). - Avoids bloated, unreadable mega-notes. - [17:17](https://www.youtube.com/watch?v=J8-1eOzQ438&t=1037) **Future-proofing** - Placeholders and headings guide future elaboration. - Long passages moved into linked notes. - [21:40](https://www.youtube.com/watch?v=J8-1eOzQ438&t=1300) **Continuous note-taking** - PKM is a living system, not a static archive. - Requires intentional, recurring updates. --- ## 📖 References: - Obsidian documentation - Plugins: Strange New Worlds, Excalibur, Note Refactor - Atul Gawande, *The Checklist Manifesto* (referenced indirectly for systematic thinking) --- ## 🗣️ Paraphrase: 1. Original: *“Coding and writing are often treated as opposites… but both abstract thought into sharable structures.”* → **Paraphrase:** While people often pit coding and writing against each other, both aim to distill ideas into forms others can understand and reuse. 2. Original: *“Having a continuous note taking system means more than just taking notes — it’s about continuously updating them to reflect what you think now.”* → **Paraphrase:** Note-taking is not a one-time act; it’s an ongoing cycle of revision, ensuring your vault mirrors your evolving understanding. --- ## 📰 Newsletter: **🗂️ Smarter Notes in Obsidian** This week we’re digging into one of the best-kept productivity secrets: refactoring your notes. Think of it like tidying up your code—only this time, your ideas are what get streamlined. Using Obsidian’s core tools plus a few powerhouse plugins (Quick Switcher, Strange New Worlds, Excalibur, Note Refactor), you can transform messy notes into a clean, connected knowledge system. The takeaway? Don’t just *take* notes—*make* them useful. Refactor regularly so your vault grows with you, not against you. 🔗 Watch the full walkthrough: [How I Refactor Notes in Obsidian](https://www.youtube.com/watch?v=J8-1eOzQ438) --- ## ✅ Action Items: - Connect refactoring to **open source advocacy**: teach contributors to evolve documentation like notes. - Apply modularization to **WordPress contributor handbooks**, making onboarding clearer. - Use refactoring analogies in **OSPO leadership pitches**, showing governance as iterative improvement. - Train community contributors to treat docs like living systems, not static files. --- ## 🧪 Hypotheses: - H1: Continuous note refactoring leads to greater long-term retention of knowledge. - H2: Visualizing links between notes improves conceptual clarity. - H3: Modular notes reduce contributor overwhelm in large open source projects. ### 📊 Methodology: - Run user studies comparing static vs. refactored notes. - Analyze retention via pre/post-tests. - Use GitHub repos as analogs for modularization. ### ❓ Questions: - How often should notes be refactored for optimal retention? - Can community documentation adopt modular structures like personal notes? - Which plugin ecosystems best support large-scale PKM? ### 🔮 Future Research: - AI-assisted refactoring tools for PKM. - Comparative studies between Obsidian and alternatives (Logseq, Notion). - Applying note refactoring to WordPress governance docs. ### 💡 Implications: - Could reshape knowledge management in open source orgs. - Supports transparency and contributor education. - Models sustainable documentation practices for OSPOs. --- ## 🧠 Learning Styles Assessment: - **Visual**: Strong (Excalibur diagrams, metadata mapping). Could add infographics. - **Aural**: Weak. No audio summary; add podcast version. - **Verbal**: Rich explanations. Could add analogies. - **Kinesthetic**: Moderate (plugins hands-on). Could add exercises. - **Logical**: Strong (hierarchies, modularization). - **Social**: Weak; no group discussion prompts. - **Solitary**: Good; journaling/reflection implicit. - **Naturalistic**: Absent; could add metaphors from ecosystems. --- ## 📊 Accessibility Assessment: - Screen reader compatibility unclear; transcripts helpful. - Keyboard navigation strong (Obsidian supports). - Contrast not evaluated; YouTube defaults adequate. - Could add alt-text to diagrams. --- ## 🌍 DEIB (Diversity, Equity, Inclusion, Belonging) Assessment: - **Cultural relevance**: Limited; technical only. Add examples across diverse contexts. - **Inclusive language**: Neutral, but jargon-heavy. Glossary needed. - **Neurodiversity support**: Strong (structured, modular). Could use more chunking. - **Representation**: Absent; could cite diverse PKM practitioners. - Summary: Refactoring notes in Obsidian involves simplifying, updating, improving the style, or restructuring the content. The goal is to make the notes meaningful, easy to find, and usable. This process includes constantly updating the notes to reflect current understanding. The author demonstrates the steps they take to refactor a specific note, including identifying the existing content, organizing the structure, categorizing the information, explaining the categorization, and modularizing the note by breaking it into smaller chunks. They use tools like ExcaliBrain and Note Refactor to assist in the process. - URL: https://youtube.com/watch?v=J8-1eOzQ438&si=zu3OBEpRde81WBYE - In programming, refactoring your code means improving it without changing what it's actually doing. So, this might mean simplifying, updating, stylistically improving, or structurally revamping your code. Developers do it as part of their work. What would it mean to refactor your notes? In this video I'm gonna talk about just that, and I'm gonna take you with me as I refactor my notes. Coding and writing are often treated as if they're on two ends of the spectrum. Coding is seen as rational and logical and very limited in its use. And writing is seen as something that's more unbounded and unfettered and verbose and creative. But when you think about it, there's no reason for this disparity. Actually, they both seek to communicate concepts, they are abstractions of thought. They're a way to distill pure thought into a form that's more freely shareable. So, I actually think that a lot of the things that apply to coding can apply to writing as well, just like refactoring. What are we actually trying to get to when we refactor our notes? Ultimately they should be meaningful, easy to find, and usable. And part of the continuous note-taking process is constantly updating your notes so that it always reflects your current understanding of a topic. I actually have a note in mind that badly needs refactoring, so I thought I'd take you with me through the process while I'm actually refactoring it. This is my Monitoring note. I've worked on it a few times and I have some things in it, but I know already that there are some things about it that aren't quite right that I'd really like to flesh out. And the thing is that it's not that anything that I said is wrong, it's more about the entire approach to the note that I think needs a little rejigging. So I'm gonna go through some steps that I use when I want to refactor a note, but don't think of it as, like, hard and fast rules. It's more of a guide, and sometimes I'll skip steps according to what makes sense in the moment. The first part is identifying what you've got and taking an inventory of what notes you have on this topic. So the first thing I would use for this is Quick Switcher, which is for me, Command + O, I type monitoring to find this in the first place. But I might also open things like this, Monitoring Tools, which I have, that maybe I'm going to want to work into it. I have a Kubernetes one, Data Monitoring and Logging. That's something I definitely want to tie everything that says Monitoring into it, all of these different types, I really need to find a way to work that in, because otherwise if it's a different type of monitoring, then I need to talk about that as well. There's also Server Monitoring, so that one is actually just going to the same place. So, I'll use something else, this push-based monitoring. See, this is kind of challenging my conception of the term monitoring, because I don't just have infrastructure stuff here. When I look at it, I also have things like Synthetic Monitoring and Real User monitoring. So, whatever I end up with is gonna have to take all of these different forms of monitoring in mind. At least, that's the ideal. Another way to inventory what I've got is also to use the Strange New Worlds plugin, and you can see that by the number here that is in the square. Strange New Worlds is a plugin that just makes it a little bit easier to see what's being linked to from where. So, I could click into the Telemetry page for example, and then be able to see all of the link mentions in it. But it is kind of nice just to scroll down this page and see what things I'm mentioning along with a number of pages that are linking to it. So, I can see that there's a lot that's already looking at metrics. So, I can scroll down here, or there's also a tab here for Strange New Worlds where I can click on something, let's say Instrumentation, and it comes up in here as well, if I prefer this to be in the side panel instead. The other way that I inventory is by using search. I like to use search when I only want to look for a specific instance of a word within a path, for example. In this case, I think Monitoring is monitoring, and I don't really need to look for it only within a certain folder, so I'm not as interested in that. But it can be useful to say something like path and then be able to select where it is here. So for example, if I only wanted to look at monitoring within certain articles, then I might choose that. And then everything that comes up in here are the things that I didn't write. They're the articles that I've imported to Reader, highlighted, and then imported into Obsidian, which actually might also be useful. So, I'm already seeing things about Shift-Right Testing, and TestOps. Usually I find when I'm refactoring notes, or wanting to anyway, that it's more of a structural issue. This is something that occurs for me. Maybe for you it's more semantic or whatever, but for me, I really like to constantly revamp the way that I'm thinking of things in my head, the way that I'm kind of putting it into a hierarchy. And that means that I spend quite a bit of time on the structure part of it. One thing that I really like to use for structural thinking and rethinking is ExcaliBrain. So, I always have ExcaliBrain open on this side panel here, but it can be, depending on the note, like this one, obviously I have quite a few notes on this. It can be kind of difficult to just be zooming in here, and it gets a little messy. So what I do instead is I move this when I'm ready to really look at it in detail, over to this side, and then I can close that right-side panel and bring myself up over here. And now I can really look at what I've got. There is a lot here in Monitoring, and I am just wanting to look at what is out there. So, I have it linked to planning for load testing. Interesting. I really like that I can also see, if I zoom in here, I can see that I've identified Monitoring as a parent. Now, this is something that I've set within the metadata itself, more on that later. But there are also numbers here and that's also telling me how many things are linking to and from that particular node or that particular note. So, I can see here that monitoring is going to have to have some sort of parent. I haven't actually defined it. I think I said Monitoring is a child of Performance test heuristics, which is interesting. So, this is really helpful for me as just a way to explore what I've got out there. I think it's a little bit messy right now. Like, I think it there should be a stronger link between Monitoring and Observability, and maybe I need to take a stance on that too. So, if I click on Observability, this changes a little bit more. I think that there needs to be a stronger link between Observability and Monitoring for sure. But also, between Monitoring and Instrumentation, I think, I need to determine what the link is there. And also something about Agents and Instrumentation. So, this is just kind of helping me visualize the structure that I really want, and also the structure that already exists. This is kind of daunting, honestly. I'm already seeing, like, going into this video I was like, "I'm gonna sort all this out." I'm no longer sure that I can, but it is giving me the lay of the land, at the very least. So, I'm gonna go here and start to put in some metadata. Now, this metadata is going to be specific to ExcaliBrain. I've made a video on ExcaliBrain, so check out that link if you want to know more on this. Right now, I just want to set some relationships so that I can start to imagine in my mind what it might look like, where Monitoring is going to fit within the rest of my notes. So, I definitely want to have a parents field, and I'm gonna say that Monitoring is a child of Observability. I think that that is probably the most obvious. I'm also actually going to say that it should be part of performance. I'm going to say that this is a list, because I want more than just Observability. I think it should be Performance as well. And then maybe it should also have some children. I think Instrumentation is going to be part of that, and I'll make this a list as well. Now, let's look at ExcaliBrain again. I probably need to put Monitoring Tools as a child of Monitoring. All right, I'm going to leave it at that for now, although that might still change. So, we've done inventory and structure. The third step for me is categorize. So, I'm going to look at the structure of the note itself. So, not the note within the structure of my vault, but the actual headings and categories that exist for that note. For that, my typical tool is Outline, which is a core plugin. And here are the things that I have in this note, what should you monitor? How should you monitor? Approaches to monitoring, and then push versus pull. I think the first thing is already, why? Why should you monitor, which I kind of already am talking about in this paragraph, what you should monitor, I think that that is fine. The how you should monitor and approaches to monitoring I don't think are great. Actually these three, I don't think that they're right. I think I have to say something about observability. So, I think this should actually be, I'm trying to only look at the structure right now and not the content. So, I'm gonna say types of monitoring, and that's also going to give me the types of things that I am monitoring. And then I think I'm going to remove this, and I'm just gonna put it within approaches to monitoring right now, this is kind of how. Approaches to monitoring. And then I think monitoring, how to expose information to monitor. And then this will be how to aggregate information. I think this is here. Okay, so this is what I've got now. Why should you monitor, types of monitoring, I think I'm going to need to differentiate between backend monitoring and also frontend monitoring. And then approaches to monitoring, how to expose information to monitor, how to aggregate it, and then tools. Okay, so this is already looking good. You'll see that I haven't really filled in any of the content. Right now, I'm looking at the structure and trying to see if this works, and I think this is already better than what I had. So I'm gonna go ahead and fill all this in and try to link notes that I already have. Step four is to explain, now that I've kind of rejigged the structure of the note and rearranged some of the categories, I want to be able to explain why I categorize things the way that I did. And then also add links to other notes that already exist, to kind of build the bigger picture of why these things are related and how. So, here's what I actually did. So, I'm skipping forward to the part where I just show you what I changed. I explained a little bit more why you should monitor. So, I'm also separating out the types of monitoring into backend and frontend. So, I'm linking to different types of backend telemetry signals in the backend monitoring side. I also added in the bit about CPU and memory utilization and tying that directly to continuous profiling. And then under frontend monitoring, I explained it a little bit, and then also cited Real User Monitoring and Synthetic monitoring. And then for the approaches to monitoring, I'm explaining how to get the information to monitor and how to aggregate the information. So, one part is collecting the information, and then the other part is sending it to some central repository. And previously these two were combined, and it didn't really make sense because, for example, something can be instrumented and used push-based monitoring. So, it wasn't a direct comparison, it wasn't like either-or. So, I feel better about separating that into two different categories. And I am looking at this and thinking that it is a little bit too wordy. So, this is a page that is very likely to get more and more detailed. So, I'd really rather streamline this and not have really long paragraphs here. I kind of want this to be a bit more like my Application Performance page, which has links to other pages rather than explaining too much in here. And that brings us to the next step of refactoring notes. Step number five is to modularize, which means you break up a larger or longer note into smaller chunks. There are a few advantages to this, and you've probably heard this referred to as the practice of taking atomic notes. I don't really like to say I take atomic notes, because the truth is that my notes are as atomic or not atomic as I feel they need to be and as I have time for. So, really I don't think that there should be a cutoff for how long a note should be, but it is useful to have smaller notes that you can address separately so you don't have to go and refactor a huge note with lots of moving pieces. Sometimes it's easier mentally to just say, "I'm just going to touch this one little thing," and I don't have to change the rest of it. Having modular notes also makes it easier to restructure later on. And especially in my case right now, this is something that I probably am going to be changing as I update my understanding of it. And for topics like that, I prefer to make them more modular. So, restructuring them is just a matter of adjusting the position of a link in a bullet point list, for example, rather than rearranging whole sections of it. And modular notes also give you more opportunities for abstracting out a specific concept so that it doesn't apply just in that context, and so that maybe you can apply it to other contexts later. So, here's what I'm going to do for this Monitoring note. I am looking at it now and I really think there are some things here that should be separated out. For example, this monitoring reasons one, I think right now there's not that much to it and probably that's also because this is already a pretty long one. So, I would like to leave space for this to be its own note. I think that there are a lot of reasons why you should monitor. And while I don't really want to go in and explain all of this now, I think it would be nice to kind of have that placeholder. So, one tool that I use for this a lot is Note Refactor, which is a community plugin. So, this is what that looks like when you use the command palette for Note Refactor. And the one that I usually use is this one that I already have a hotkey for, and it is to extract the selection to a new note, and it's going to use this first line of whatever I highlighted as the first name. So, I'm going to select that, and what that did was it created a new note called "Why should you monitor?" Now, I don't really want that as a name, so I'm going to change it to "Reasons for monitoring". And then I'm just going to put my standard boilerplate template there for new notes, and I am going to just leave it at that. Below are some reasons why you should, and I'm going to add a link as well to the monitoring page. Now, this is obviously going to need some work, but at least I'm kind of reminding myself that this is something that I want to get back to later, because I'm sure that at some point I'm going to look at this and just be annoyed enough to flesh this out. Now, going back to the Monitoring note, I'm just going to add this as a heading, but I'm not going to elucidate further. I think the types of monitoring is something that maybe might need to be pulled out at some point, - But right now I think this is pretty terse, so I'm going to leave it at that. The approaches to monitoring I do need to do something about. I'm actually thinking that maybe this is all that I should have and all of this needs to go somewhere else. In this case, I think this part needs to go in the Instrumentation page. So, I'm going to go to the Instrumentation note, which I already had, and I'm just talking about instrumentation agents here, so I'm going to add that here. I'm going to call it "Types of instrumentation", and I'm going to leave those there. Actually, I think this one should probably be fine, but this is definitely way too long. So, I'm going to select that again, and then this time I'm going to use the hotkey for the refactoring, and that basically did the same thing. I'm going to put my boilerplate template there, and I'm going to link this, for sure, to monitoring. I'm gonna call it "Aggregating monitoring data" as well. So then going back to the Monitoring page, I'm going to leave this in here under "Approaches to monitoring" as well. So, that's how I personally refactor my notes. I first start with taking an inventory of what I've already got, and for that I use the core plugins Search and Quick Switcher, as well as the community plugin, Strange New Worlds. And then I start to look strategically about how I want to structure that note in terms of the other notes in my vault. For that, I really find Obsidian ExcaliBrain useful as a community plugin for that. You are also going to need the Excalidraw plugin, because the two are related, and in this step it's more about trying to see how notes relate to other notes. The third step is categorizing, and I look at the headings and categories that are inherent in the note, and I try to see if I would restructure the content of the note itself in a different way. Step number four is explaining, and this is probably the step that takes a lot of time. because this is where I go in and flesh out the new structure that I've created, and then also the categories within the note. And then number five is modularizing. That involves looking at the different headings that I've identified and already fleshed out, and then using the community plugin Note Refactor, or really also just copying and pasting into other notes, so that I can start to tease apart separate ideas that probably should be in their own separate note. Just to give you an idea of what I changed in the course of making this video, here is my changelog which automatically updates according to the notes that I've changed. And everything that I'm highlighting here are things that I significantly changed, actually, just in the process of changing this one note called Monitoring. On one hand, it seems pretty obvious that refactoring your notes takes a lot of time. It requires sitting down, reviewing your notes, and thinking critically about what notes need to be changed, how, and why. On the other hand, it is precisely this type of work that differentiates just taking notes from having an actually usable personal knowledge management system that is an accurate reflection of what you're thinking at any point in time. Having a continuous note-taking system means so much more than taking the notes in the first place. It means continually updating your vault as what you think changes as well. If you'd like to learn more about continuous note-taking and some best practices for it that I've stumbled across in my years of doing it, then check out this video, where I talk specifically about how I use Obsidian for work, but it's still going to be valuable in other contexts. Thanks for watching, pfiat di., How I Refactor Notes in Obsidian, Nicole van der Hoeven, 01hgnpsq9k0we5zwb7yds9ckbx.