Errors and quality control

grayen

After reading @Will recent comment I wanted to reply to ask about what more potential errors he is aware of in Zettels, but it felt off topic, so I started this new discussion.

I made a custom VS Code extension to help me apply the Zettelkasten method, so I could easily customize it to fit my needs. One panel in this extension shows me a list of Zettels that have errors within them. So far I have recognized 3 different errors:

• UID unavailable: The Zettel's UID is not presented anywhere within the Zettel.
• Unconnected: The Zettel has no outbound (i.e. regular) or inbound (i.e. back) links.
• Deadlinks: The Zettel contains links that point towards non-existing Zettels.

What other errors might occur for a Zettel?

As part of my workflow, I plan to indicate the state of a Zettel as part of its metadata, i.e. whether it is a brain dump, draft, or processed Zettel, or some such. So for quality control I plan to add to my workflow that I first have to be able to find the my Zettel by searching for it based on its content, and only if I am able to successfully search for it can it progress to become a processed Zettel. If not, I might need to add some missing keywords.

What other quality control measures could there be for a Zettel?

MikeBraddock

@grayen I have been pondering if I used quotes or block quotes do I have citations. This will be a valid error condition if you are using references I would think.

Will

A couple of additional 'errors' I'd consider would be:

1. Biblio-Data Missing: What parts of the Zettel are direct quotes, paraphrases, my thoughts and questions. Including any references to sources.
2. Creation date included: Especially if you UID isn't a date format.
3. Is structure note complete: Some way to tell if a book/paper/lecture has been fully processed or not.

I'm sure there are 'errors' that could be added.
A note about 'errors'. I view these not as mistakes but as missed opportunities and reminders of how I would want my Zettels to integrate into my Zettelkasten. In that light, I wouldn't use these as tools to beat myself up with and I wouldn't call them errors but maybe a #2DO or #4WORK or #2FINISH list.

To solve the first 3 types of errors you mention. Use digital technology to help where we can.

1. UID unavailable: This should be automated. As part of creating a new note, certain metadata should be populated into the blank note. I never start with a blank note. When a note is created the level-1 Markdown heading is created and a small meta footer is generated by the software. This prevents me from having to think about this and remember to manually add this.
2. Unconnected: @ctietze shined the light on this for me in his video processing of the "Range". Always start a Zettel from another Zettel in your Zettelkasten. A Zettel always starts with a link in and established note. Then the new Zettel will have at least 1 incoming link.
3. Deadlinks: Just don't delete notes. Changing links is also a sticky wicket. If the UID is the only part of a Zettel that is used as a link then you can freely change the title of the Zettel without breaking any links. You could set up your software such that a Zettel could have multiple UID's. Both UID's and their associated links would work.

grayen

@MikeBraddock Good one! I have added it to the list. @Will Error is indeed too strong a word, I will name them warnings for now, i.e. something to look out for as potential problems. Your "Biblio-Data Missing" makes me thing of what was discussed here. You are right that technology can help solve or assist in most of these warnings and quality control. Though I consider the quality control items to be part of the workflow, something that cannot really be automated or maybe even shouldn't be automated to begin with, as its good to go over these manually as part of the process.

These are my updated lists after incorporating your comments and some new ideas I have had since:

Warnings:

• UID missing: The Zettel's UID is not presented anywhere within the Zettel.
• Unconnected: The Zettel has no outbound (i.e. regular) or inbound (i.e. back) links.
• Deadlinks: The Zettel contains links that point towards non-existing Zettels.
• Uncited quote: The Zettel contains quotes without a source.
• Unknown reference: The zettel contains a reference that could not be found in the reference manager. This is somewhat similar to deadlinks.
• Creation timestamp missing: The Zettel does not contain its creation timestamp, a piece of information that can be crucial in putting the Zettel in the right context.
• Source unavailable: The Zettel uses a source which might not be available, e.g. make sure to create a local copy of a web page available when you use it as the source.

Quality Control:

• Content-based search: The Zettel needs to be found when you search for it based on its contents, if you cannot, you likely need rephrase some of the content or add keywords/tags.
• Uncited quotes: You cannot consider a Zettel complete if its still has uncited sources. You might return to the Zettel in the future and no longer remember the source, or whether it was an exact quote or paraphrased without the source properly mentioned.
• Unfinished review: You did not complete reviewing a source. This has to be part of some manual quality control step unless you make this measurable by e.g. tracking how far you've progressed, then it could also be turned into a warning.
• Meaningful links: Is it clear why each link in the Zettel has been made? Can you answer this based on what is there within the Zettel and its surrounding context?
• Unambiguous quotation: Is it clear whether a quote is a literal/direct quote or whether it has been paraphrased? And is at all times clear to whom a quote should be attribute too, is it something you wrote yourself, or something of others, and if so, who. This can get ambiguous when you mix those close to each other.

MikeBraddock

@grayen In my experience at what you are attempting after you are up and going and getting warnings and errors, you will find a time when you want to suppress something you decide was intentional. Then you know you have addressed it, and it doesn't need to keep getting into your view.

At first glance, you might say, "Nah", I am ok seeing them all the time. Suppose you imported a zip file of zettels from someone that you may want to include in your ZK but don't want to bring them into compliance with your error/warning criteria.

Thinking of it now as opposed to an afterthought may be helpful.

grayen

@MikeBraddock That is indeed important to keep a pleasant experience while working in the Zettelkasten. I would address that by adding some kind of marker on those Zettels to indicate they should not be checked. I plan to workout a nice workflow and the right markers for my Zettels when I finished the Getting Things Done book I am currently reading.

MikeBraddock

@grayen Great discussions and comments. Very insightful. I just wanted to say thanks. Keep them coming.

cobblepot

@grayen , I really like the idea of setting up software in ways to 'nudge' users into good practices. You might distinguish between something like a linter (which I just learned about this week!) aiming to standardize formatting and syntax, and something more akin to a grammar checker that aims to encourage/discourage practices by nudging the user to check whether a certain type of content is correct or not.

@grayen wrote:

I would address that by adding some kind of marker on those Zettels to indicate they should not be checked

In addition to letting users mark notes as "don't check this one," maybe 1) give the user the ability to deactivate particular types of checks on all notes, 2) allow the user to toggle on/off checking notes.

grayen

@cobblepot Yeah, that is what I had in mind when I started this discussion. At the time I already implemented two of the warnings, those for unconnected Zettels and Zettels containing deadlinks, but as part of my VS Code extension. If made configurable enough, it could indeed be implemented as a set of scripts and be made into a linter of some kind.

In addition to letting users mark notes as "don't chick this one," maybe 1) give the user the ability to deactivate particular types of checks on all notes, 2) allow the user to toggle on/off checking notes.

The marker thing was more of an example. I actually prefer not to be too specific about it, I would probably implement it by allowing to run / or don't run certain checks based on search results, which could be a search result based on some marker.

JustinW80

I'm a systems engineer, and one of my responsibilities is requirements traceability. I've been noticing a lot of overlap between the Zettelkasten method and traditional requirements management.

I've been applying the lessons I've learned from my Zettelkasten implementation to requirements traceability, such as plaintext and version control (we call it "docs like code" in technical writing community).

Anyway, I think some of the plaintext requirements management tools that I use could help with some of these error checking in a Zettelkasten.

Doorstop is a Python module that helps store requirements in YAML files in a git repository and then runs traceability checks. Unfortunately, storing the data as Markdown files with a YAML header for metadata is not implemented yet. But Doorstop reports warnings to me when I am missing links.

The other tool is Vale, a prose-aware linter. You can easily define some of these rules, such as the check if the UID is present in the Zettel's body, and the VS Code extension will highlight it for you as a warning.

cobblepot

@JustinW80 said:
I'm a systems engineer, and one of my responsibilities is [requirements traceability]...
I've been applying the lessons I've learned from my Zettelkasten implementation to requirements traceability, such as plaintext and version control (we call it "docs like code" in technical writing community).

@JustinW80 , I really look forward to hearing how your experience can help us improve our ZK systems. Can you tell us your ZK implementation?

I have heard a lot about version control in expected contexts like GitHub, but I'm not sure whether it's actually a good idea for a ZK. What are your thoughts? Feel free to start another thread on that if it doesn't fit here

ctietze

Extracted a sub-discussion about a concrete "finding orphans" implementation into its own thread: https://forum.zettelkasten.de/discussion/1074/quality-control-finding-orphaned-zettel

JustinW80

@cobblepot said:
@JustinW80 , I really look forward to hearing how your experience can help us improve our ZK systems. Can you tell us your ZK implementation?

It's more in the other direction, that implementing a ZK as an flat directory of atomic text files with unique identifiers helped inform the docs engineering I do in my day job. Instead of a monolithic specification document, I store requirements in just like Zettels and link to them as needed. It's much more agile than a big hierarchical spec up front.

I have heard a lot about version control in expected contexts like GitHub, but I'm not sure whether it's actually a good idea for a ZK. What are your thoughts? Feel free to start another thread on that if it doesn't fit here

Maybe it goes in its own thread, but my version control setup for my ZK is not doing anything powerful with git. On my daily laptop, I have a task scheduled that fires hourly to add all the files in my zk folder and commit them. Then once a day, another task pushes them to a private repository on GitHub. That way, I have hourly snapshots of whatever my zk folder looks like, and the entire history is backed up.

Not just backed up, but I can sync it that way too. (Dropbox, etc. are blocked at work.) On my home machine, I can git pull to get all my updates from my work laptop. I don't have all the automation set up at home since I don't work on it that much. So I do any version control operations manually.

I'm not doing any branch-and-merge workflows unless I am doing some large undertaking such as bulk edits to large groups of files or something.