Zettelkasten Forum

Emerging overview with structure notes


I want to share the gist of a few recent happy moments of Zettelkasten note-taking with you and find out what you do in your work to achieve a similar effect -- or if all of this is totally new to you.

Against all odds, I did manage to write a Zettel note or two during 2017. I did not process all (any) of the interesting books I read, but I took notes while working on my current app project, The Archive. In the meantime, I read @sfast's draft for the 2nd edition of the Zettelkasten Method book and gave more thought to structure notes.

Back when I started with the archive, I created INDEX notes to, well, create topic index notes. They mostly contained definitions and a few outgoing links (my archive was very small back then, so there was not much to link to at first). Along the way, I ditched the concept of "index" notes and only recently rediscovered the utility of structuring topics with dedicated structural notes.

What I found out was:

  • The old INDEX notes have to be "refactored": I have to extract the definitions into dedicated definition notes and leave a link to them in the index. This could revive the index notes.
  • Taking notes for ongoing research and grouping the resulting notes in overviews immediately gave an additional feeling of closure. Even more so than adding a link from a large project buffer.
  • There is no such thing as merely collecting source code; in my case, most of the interesting notes of 2017 consist of interpretations of Apple's programmer documentation, code snippets and samples, and collections of tips from around the web regarding text editing -- in short, stuff that's suitable to be assembled into blog posts for my programming blog. More than 80% of the programming notes contain far more than source code snippets. I can append interpretations and reasoning even to something as unambiguous as code.

Here is an example of a growing structure note about typewriter-mode text editing that is also a project outline:

Title:  Approaches to a Typewriter text component
ID:     201707081109
Tags:   #nstextview ##outline #typewriter-mode

## Conceptual

- [[201707111650]] Essence of the Typewriter Mode
- [[201707121227]] Flavors of Typewriter Mode
- [[201707111640]] Overscrolling is essential for typewriter modes
- [[201707111646]] Regular scrolling without overscrolling described
- [[201709191053]] Animate programmatic scrolling in NSScrollView

## Implement scrolling

- [[201707111651]] Implementing Two-Sided Overscrolling in a NSTextView. You'll need that for typewriter scrolling with focus lock.
- [[201707111654]] Implementing One-Sided (Bottom) Overscrolling. That's useful for non-immersive situations like text editors or note-taking apps that provide an extra nice user experience.
- [[201707041426]] NSScrollView scroll notifications. You need to adjust the insets as the view resizes.
- [[201708231318]] Avoid NSTextView scroll to bottom of document in typewriter mode

## Implementation TextKit components

- [[201707081135]] Subclassing NSTextStorage
- [[201707081137]] User-initiated text change callback from NSTextStorage
- [[201707081110]] Keeping the insertion point centered
- [[201707071026]] Typewriter scrolling without flashing scroller knobs


- [[201707111623]] Line height in a NSTextView
- [[201709260927]] Debug output for NSTextView width and insets. Used in _The Archive_ to find out why changing window sized and fullscreen mode didn't work properly.

Although this is tagged ##outline, it's not yet outlining a comprehensive guide. It's work in progress, but I know it's going to be a writing project already. Not every structure notes has this tag; them being structure notes is not marked in any way.

Here is a shorter one on an implementation detail that requires a few code components to change at the same time:

Title:  Working with NSTextFinder find bars in NSTextViews
ID:     201712021110
Tags:   #nstextview #nstextfinder

- [[201712021109]] How to validate NSTextFinder actions
- [[201712021352]] How to write a custom `NSTextFinderClient`: use a thin adapter for `NSTextView`
- [[201712021421]] Use `NSTextFinder` from anywhere by bypassing `performTextFinderAction`, using a custom selector instead.
- [[201712021446]] Reset `NSTextFinder` on programmatic string changes (obsolete with a custom `NSTextFinderClient` setup)

## Programmatically remote-controlling find bars

- [[201712021021]] Close the find bar programmatically for `NSTextView`s
- [[201712021111]] Invoke the find bar from different view components

The last example is grouping together 1 high-level explanatory note and various annotated implementation details. I know I'll need this in other projects, and I know I'll have forgotten about the intricacies by then. So this is a good entry point into the topic of "How to use NSTextFinder". You can see from the Ids how this little cluster grew. over the course of one day.

I know @sfast is using structure notes a lot for quite a while; I think he's tagging all of them to denote "this is structural", which I apparently don't. (Making it harder to assemble a list of structure notes, like I wanted to have today when I drafted this conversation.) I only recently discovered their utility and am still experimenting, and I think I'll add meta-tags to them, too, to cover the case when I know that I did write a structure note sometime last week, but cannot remember what the topic was.

  • Anything that comes to mind which I overlooked so far?
  • Do you branch off of detail notes and assemble overview notes of some sort?
  • How do you make sure you use your Zettel notes?

Author at Zettelkasten.de • https://christiantietze.de/


  • @ctietze said:
    the case when I know that I did write a structure note sometime last week, but cannot remember what the topic was.

    As funny as it might sound, I really like that approach.

  • I'm not sure a consensus was ever reached in the Great Folgezettel Debate, but it seems to me that some kind of summary or table-of-contents note with a list of links to the notes that flesh out various aspects of an extended topic is the obvious-in-retrospect digital implementation of what might be organized as a Folgezettel sequence in a paper system.

  • I think you are spot on. The underlying principles are structure and trail of thought. Folgezettel are one method of putting them into practice.

    I am a Zettler

  • When you create structure notes are you just going one level down into high level topics, leaving subtopics as links in the topic notes you reference? Or do you bring subtopics into the structure note as well?

    It seems like you guys encourage a flat structure, so im trying to understand better how you mark topic/argument and support notes. I'm curious about the trade-off from leaving hierarchy to structure or project notes vs letting notes become embedded deeper and deeper into a vertical chain of notes.

  • It is both. There is no exclusivity. The direct linking structure is organic and not controlable. The structure notes are more like a surfboard to ride on a big wave of past and present thought. :smile:

    I am a Zettler

  • @ctietze I'm playing around with overview and structure notes. I'm thinking about how to capture my code learnings in my ZK. Would you be willing to post one or two of the actual notes you show in your overviews?

  • edited October 2018

    Sure, here are two with code:

    Title:      Implementing Two-Sided Overscrolling in a NSTextView
    Date:       2017-07-11 16:51
    Keywords:   #typewriter-mode
    To tell the `NSScrollView` that you want to scroll beyond the confines of the text, you need to tell it that its `documentView` is larger than it actually is. I found increasing the vertical `textContainerInset` to work pretty well:
    class TopAndBottomOverscrollingTextView: NSTextView {
        func scrollViewDidResize(_ scrollView: NSScrollView) {
            let lineHeight: CGFloat = 14 // compute this instead
            let overscrollInset = scrollView.bounds.height - lineHeight
            textContainerInset = NSSize(width: 0, height: overscrollInset)
    - See: [[201707041426]] Make NSScrollView post scroll notifications
    - See: [[201707111623]] Line height in a NSTextView
    Now you have increased the text view's total size by twice the container height, so you have extra space around the document:
    ![Top overscroll indent](media/20170711165315_overscroll-top.png)
    ![Bottom overscroll indent](media/20170711165359_overscroll-bottom.png)


    Title:      NSScrollView scroll notifications
    Date:       2017-07-04 14:26
    Keywords:   #cocoa #appkit
    To receive notifications when the user scrolls or programmatic scrolling is initiated:
        scrollView.contentView.postsBoundsChangedNotifications = true
        NotificationCenter.default.addObserver(self, selector: #selector(boundsDidChange(_:)), name: .NSViewBoundsDidChange, object: scrollView.contentView)
        func boundsDidChange(_ notification: Notification) {
            // ...

    Author at Zettelkasten.de • https://christiantietze.de/

  • Thanks @ctietze. That's a great example. For code stuff, I've not made zettels but rather keep long Jupyter notebooks or R Markdown notebooks since you can see output. I feel like it's a better medium for code notes. What do you think? Or do you note care about seeing output in line?

  • I like in-line code execution in TextMate for Ruby code I write, if I write it, but that's so seldom the case that I don't miss it. Since I write in compiled languages only, there's no use in executing lines of code for me personally.

    I do love that you can run code in Babel blocks of Emacs Org mode, though!

    Author at Zettelkasten.de • https://christiantietze.de/

Sign In or Register to comment.