Plain-text vs Outliner Focused Features Discussion

Development
1

There was some discussion/interest in these two approaches and the trade-off between, in the org-roam Slack, when thinking about future features. The definitions of “outliners”, here, is not fully precise for me yet.

For those of you who haven’t already, I would encourage you to look at Roam Research, Dynalist, Workflowy (and other outliner apps) in some detail and contribute to this discussion about their thoughts when compared to org and OR. I think “outliner” is a bad way to describe these apps, I think “bullet-pointer” is a better term (Please read the post below to see what I mean by outliner so that we are clear about what we mean.).

I will start by some thoughts from my discussion in Slack thread:

TL;DR : After some internal debate I really think that future features relating to links/backlinks should be at the bullet points/subheadings level (with nesting). Two obvious examples are transclusions and backlinks context. This is in opposition to the whole org file/note which I think exposes too much information; and on the opposite end having just the link which exposes too little information. Currently I’ve seen other apps that use the whole note for transclusions, and (at the moment any way) paragraph context for backlinks in org-roam. I think this really comes down to plain text vs outliner, but I’m really hoping that org-mode/emacs allows us to have the benefits of both worlds.

Full Discussion:

I think we have different ideas of what we mean by outliner. Of course, I agree that you can still continue to “outline” in OR in the normal sense i.e. using bullet points, headings/subheadings etc. But “outliner”, software like Workflowy, Dynalist, Roam Research are based on the philosophy that the bullet point being the smallest unit, rather than the whole note (i.e. org file). And sure you can mimic in org and so OR, by limiting a single idea to each org-file — though this will probably complicate things. I am probably missing something, I am not an avid org user, but I would say that org lies closer to the plain-text side of the spectrum when compared to the above apps.

I think the bullet-atomic approach is worthwhile. It is more flexible, and allows for what is now being called “threaded thinking” (see Roam Research twitter et al. (two links; see references within)). Outliners group bullets into a page/note, but link and transclude at the bullet level — maintaining the advantage of both approaches.

To be clear, I am not advocating against plain text at all. Among other things I love the idea that plain text is human readable (to some extent) and there is virtually 0 vendor lock-in involved, and you own your data. I love those things, and I think any Personal Knowledge/Management system should have these as core values. Outliners, currently aren’t plain text and are typically dependant on vendors, so do not have these advantages.

However, there are advantages to outliners which unfortunately aren’t readily avialable with plain text (and of course vice versa). The obvious examples, as I mentioned is transclusions (i.e. block refs) and black links context. I think this is what makes Roam Research powerful. Not the features themselves alone in a sperate manner, but their combination. It is an outliner AND has black links (with outline context) AND has (bullet-level) transclusion. Now, if we can add plain-text to that mixing pot, I think we have a very powerful platform for something amazing.

In fact, I don’t really see the point of transclusion if it is not at the bullet point level — if you have links why would you want to embed a whole org file into another org file. You could just have a link to the second org file and view it separatly. Allowing for selective transclusion is what makes it powerful, it gives you the choice to include only that which you deem relevant. And this will be updated automatically, should you chose to do so. Bullets (ideas) can now live in more than one place. Note, “live” is the operative word here — the transclusion is “alive”, whenever you update a thought/idea/point it is updated where ever you have transcluded. Your notes are evolving at the same pace as your learning. Cognitive effort used to make association have a bigger return on investment in the future. And you can make associations more boldly knowing that if you change your mind, these will be updated too — no association becomes outdated (unless you chose to do so).

Tbh, I think that on the surface level OR could achieve “plain text pseudo-outliner” / or at the very least approximate nested bullet level context. Am not so sure about transclusion, although I think that would be very powerful. And users that want to avoid this complexity should be given the choice to opt out. I feel like that an outliner is more granular and so its not impossible to avoid the complexity should you choose to do so. Any way nesting is already a thing in org, so users are somewhat used to them anyway.

Summary : I think I can narrow my argument down to this point: backlink context and transclusion (and relevant future features) should be at the heading level. Perhaps not specifically in O-R, but more generally in org.

2

Let me ask: Without (relatively easy) transclusion, do you still see a point for bullet-point level linking? The only thing I can think of is simply allowing multiple note-taking styles, rather than any concrete benefit. I would love transclusion, but I get the impression that (while people are working on it) they are not going to be here soon. Someone tell me if I’m wrong!

I think it’s reasonable to try and include linking to headings (I wanted it when I first found org-roam) in the future, but that’s a farcry from bullets, and I’m not sure what new feature header links really get you (without transclusions, I mean). It’s a difference in note-taking style, not really a revolution in functionality.

Can you elaborate on the “threaded linking”? I’m been looking over Roam’s media every so often and I don’t recall this term, and I don’t see anything on their twitter about it. Do you mean like nested transclusions?

3

Thanks for posting this @rooster.

I do think the post could use a little more structure, though. It’s hard to read as is. Maybe add some more paragraph breaks, and bullet points?

Beyond that …

I think the key thing you’re missing is org-roam is merely an extension of org, which is a powerful, infinitely-flexible, outliner, note-taker, project-management tool, etc.

This is an advantage that OR has over other options out there, including Roam, because it means it can provide a more focused UX.

My view is that OR:

  1. should focus on making note-taking and idea development as optimized as possible, consistent with the basic model and approach of zettelkasten.

  2. should not concern itself with other aspects better left to org more broadly; project management, manuscript outlining and drafting, etc.

4

On Slack, @rooster asked (I just saw), this question:

I am interested in your thoughts on transclusions? Do you agree it should be block transclusions?

… and narrowed down to this statement:

I think I can narrow my argument down to this point: backlink context and transclusion should be at the outline level.

… to which @jethro responded:

we can definitely show more context where the link is in an outline.

Transclusions will not be implemented by Org-roam, and is a community effort: https://github.com/alphapapa/transclusion-in-emacs

I am unsure about transclusions in this context, but am happy that it’s a broader effort in emacs; should allow for a more organic process to figure out how best to apply it within OR.

BTW, @rooster, this package seems the most recent and ambitious?

5

Yes, I agree with (sub)headings-level linking, I think this is what I meant by “bullet-level linking”. I think the miscomuncation is arising from what “outline” and bullet-points means in org mode (and so org-roam (OR)) vs what it means in an “outliner”. I think the apps that I am calling outliners don’t really outline in the normal sense, i.e. in what it means to outline in org, see post below for some clarification (I thinki “Bullet-pointer” is a better term).

You do make a fair point in regards to functionality, but I think this is a revolution in note-taking style. The arguement being that note-taking is the thinking process, and so this bullet-point focused note-taking style leads to “threaded thinking”. Perhaps this a discussion about note-taking style rather than functionality, althought they are obviously interlinked.

Threaded thinking not threaded linking. I have added link 1 and link 2 to the OP, see also references therein. Not nested transclusions, but that could be interesting. “Threaded thinking” is more general than Roam Research, but I think they’ve created the best use case so far.

I have much more to say to this, but I think it would be better to include this in the post below to keep this reply consistent. I would love to hear your thoughts.

6

Ah, didn’t spot that. Fixed and added links. I do apologise for the unstructured thought, it was more of a ramble/brain dump to entice discussion than anything.

I do see your point, I think some of the disagreement is due to blury definitions. In particular I think we have two different meanings of what outline/outliner means, I’ll expand on this in the post below.

Agreed, although OR should not force one note-taking style over the other. If I wanted to do a bullet-point focused note-taking style (see below for what I mean by this) in org and OR, I should be able to.

Cool, thanks — will look into it.

7

A few comments on the original post.

There was some discussion/interest in these two approaches and the trade-off between, in the org-roam Slack, when thinking about future features. The definitions of “outliners”, here, is not fully precise for me yet.

For me, one essential function of an outliner is allowing text in nested hierarchies, and a 2nd non-essential (but practically essential) function is folding child branches under a parent. Org-mode provides both of these. Everything else is potentially nice but not essential.

Org-roam (can we abbreviate as O-R maybe? OR is so confusing) simplifies internote links and presents backlinks when editing notes.

I am very interested in transclusion but understand that implementing it at a sub-note level (i.e. a heading or bullet point level) is vastly more complex than simple whole-note transclusion.

In fact, I don’t really see the point of transclusion if it is not at the bullet point level — if you have links why would you want to embed a whole org file into another org file. You could just have a link to the second org file and view it separatly.

To me the benefit of transclusion is in the process of organizing ideas for writing, not the process of reading text to relate ideas. When reading, I agree that transclusion is not that different from following links. But when trying to outline ideas into a linear written form, being able to organize a note summary (whether the actual note title or not) and have the complete written idea transclused into a longer paper, where it can be read as part of a larger essay, seems potentially very useful.

The problems with whole-note (whole-file) transclusion are 1) front matter would make this type of “transclusion into essay” visually messy and 2) it does seem to work only with one-paragraph notes rather than longer notes. Problem 1) could potentially be dealt with by hiding front matter when notes are transcluded.

I think I can narrow my argument down to this point: backlink context and transclusion (and relevant future features) should be at the outline level.

This ending confused me - what is “outline level”?

1 Like
8

So, I would like to propose the term “bullet-pointer” to replace what I mean by outliner. By bullet-pointer I mean apps like Dynalist, Workflowy and of course Roam Research. In these apps, you can only input text (at the basic level) as either two things:

  1. Title
  2. Bullet points (with collapsable nesting obviously).

Loosely speaking, virtually everything is, or is part of, a bullet point. This is perhaps, a more note-taking style/convention/philosophy than anything else. To understand more, I think it is straightforward to replicate this behaviour in org. Essentially, if I wanted to use org as a bullet-pointer (as I have defined it above): everything I write should be in a (sub)headline. In other words my org file would look something like this:

* Point one
** Nested Point one
* Point two
** Nested Point two_a
** Nested Point two_b
* Point three

But I should never do this:

* Point one
Some text, or the other.....
** Nested Point one
* Point two
** Nested Point two_a
** Nested Point two_b
* Point three

Importantly note that I am not using the outline nature of subheadings, instead I am treating them as bullet points. I am not using the headings to outline a manuscript for example, but as nested bullet points. Now, I know there are bullet points in org but doing the above means I can exploit some functionality of org. Indeed, functions like org-refile work at the heading level (under the said note-taking style, I would call it at the “bullet-point level”). The confusion of calling this style an outliner should now be clear.

In a bullet-pointer, linking, back-link context, and transclusions should naturally be at the bullet-point level (read heading-level for org users). I think this is somewhat obvious. Now, I would argue that being a bullet-pointer is a core identity of Roam Research. It has profound effects to approaches to current and future features in Roam. It’s not just back links that makes Roam Research what it is.

I think that org-roam should have the option to allow for bullet-pointer note taking. At the very minimum, and I think most people agree on and would like to see this: backlinks context should include nested elements where the link is part of a heading. I think this would benefit even non-bullet-point type note-taking styles. Until then, I would argue that org-roam would be better described as org-backlinks. Again, not undermining the importance of backlinks and the work done already I am very excited to see where this goes.

This then leads to the arguement, should relevant future features (such as transclusions, which I admit is more general than OR) also be done at the heading level where appropriate/possible?

9

Has anyone tried this package? I’m an emacs newbie so I haven’t been able to figure it out, but I would love to read any type of review/discussion of it.

10

Agreed, transclusion does seem like a complex thing to implement. Fortunately, it has utility outside O-R and people seem to have interest. Perhaps, I am asking for the too much because doing this while mainting plain text format seems near impossible!

Fair point, I did not consider this — I was thinking in terms of note-taking rather than producing an article. Perhaps this is more personal taste thing than anything else, even within note taking? Anyway, you’re in luck as I think whole-page transclusion would happen before sub-note anyway :smiley:.

I meant sub-note level, fixed it now.

12

OK, I get where you’re going. You like how Roam models content, and want O-R to behave the same?

Isn’t your complaint really with org?

13

Well yes and no.

(I’ll use org terminology here (i.e. headlines instead of bullet-points), althought I think it will beconfusing for bullet-pointer users.)

To the extent that it can, org already allows for bullet-point style note taking. It has functions that work at the headline-level (e.g. org-refile). The Roam model (bullet-pointer) means linking, backlinks and transclusion happen at the headline-level (with nesting). Like I said before, org-roam has implemented backlinks for org users, but not at the headline-level. And by that I mean the backlinks context only shows the paragraph/line that the link is in. This is contrary to the Roam model which includes nested elements in the backlink context — because headlines are the unit with which it works i.e. there are only headlines in Roam. Backlinks are a feature of org-roam, not org so I think it is good to have this discussion in this context.

As mentioned before, in the current state it’s more precise to call this implementation “org-backlinks” rather than org-roam. I think it is a oversimplification to think Roam is just backlinks.

14

Yes the style is definitely very different, and it seems likely there will be a mix of people who like one over the other (or groups may find one better for their type of work). Linking to headlines is at least doable vs. what I thought you were previously asking for (basically links to any line of text).

Using headlines as bullets is certainly not the spirit of org, but I’m sure you’re not the only one. Without transclusion and O-R linking headlines there are still hacky solutions to at least get a little bit of what you want. Is it worth the effort? I don’t know – it definitely won’t be Roam.

I would be curious how Roam manages its links behind-the-scenes. The bullet level linking is different from the page backlinks. Page backlinking can be done as you write, but the bullet-level outlining (between pages at least) requires some more intentional effort I think. Implementing something even close to this in O-R I think would require maintenance of two separate linking mechanisms.

That explains a bit :laughing:

15

Meaning what?

  1. That backlinks don’t work at the headline level? As in, rather than doing O-R links to files, one should (also) be doing links to subfile headlines, which get reflected in the O-R backllinks buffer. Or …
  2. Simpy that, per @jethro’s response, the backlinks currently don’t show enough context (which he agreed with)?

Or both?

1 is a more controversial point than 2, I think, simply because it’s (much?) more technically complicated to implement (as @zaeph has mentioned in a few different places), and also because it necessarily makes the UX more complicated.

16

Yes, hence my confusions over bullet-points and headlines and outliners. Adding to the confusion, is that nested bullet points do exist in org but they are obviously different to headlines. It’s weird that org users only understood what I meant after I explained it using headlines though— I guess they are more used to seeing functions that work at the headline level, as opposed to bullet-points (in org). I have a feeling it may be problematic to force this note-taking style into org, via use of headlines.

Anyway, regardless of note-taking approach — I still maintain the point that features at the headline level will be much more useful (admitidly at the cost of complex implementation). Even if you don’t use a bullet-point notes, you can make use of headline-level functions.

17

Pretty much all structured document formats (which is the way I and probably many others here think about documents), from html, to docbook, to latex, to markdown, to org all have basic structural elements typically called sections or section headings, and then treat lists (bullets and ordered lists) differently.

18

Actually, thanks for pointing this out. I think I am argueing for both. I think point 2 is a bit specific and I am aware that there will be changes to the backlinks. My point is that relevant future features should be headline-level focused.

You’ve actually helped me formulate the arguement for headline linking more clearly ! This is why discussions are so important.

I can see 1 being made possible by using something like org-narrow-to-subtree, although I don’t know Lisps. The term used for this in Roam is “precise links”, essentially you link to the headline in any orgfile and it opens up that headline in org-narrow-to-subtree mode. This is very powerful if you have org files with many headlines and you just want to link to a specific part of it (regardless of notetaking style). Transclusions would be very similiar to this but happen in the same window.

1 Like
19

Not problematic; just not what they’re usually meant for. If it’s what you want to do, I don’t think you lose anything or break some existing org functionality. Exporting to html or something would look funky, but again it would be fairly easy to come up with hacky solutions around those types of issues.

20

@rooster - I think the issue is this. Org-mode has headings and list items that function differently. Roam has only headings, in the sense that all text levels have the same functionality (except for page titles, maybe?). You prefer the 2nd way, which would mean that any org-mode functionality for headings would also be available for list items or other text. Is that right?

Can’t you currently achieve this by just using org-mode and putting everything in headings and nothing in list items?

Also:

The arguement being that note-taking is the thinking process, and so this bullet-point focused note-taking style leads to “threaded thinking”. Perhaps this a discussion about note-taking style rather than functionality, althought they are obviously interlinked.

Although you seem to like the idea of having all thoughts “threaded” into a structure, I think forcing this would undermine some advantages of the ZK process.

21

Yes. I think I mention this method in one of the above posts. Now, that I have had time to experiment around with it, I think @bruce is right after all. I think my complaint is with org-mode rather than org-roam. By doing what you suggest, using headlies and nothing in list items, I would require an overhaul of many of org’s functionality. Sure there are headline-level functions but I think they distrupt the the bullet-pointer workflow e.g. time stamping completed task (TODO->DONE) involves putting text under headlines. This would be avoided in bullet-pointers.

I think for my uses I would be better of using Roam Research. Org has its own syntax, which at times are orthogonal to bullet-pointer style approach. If you are forced to not use alot of Org’s functionality, because of this, you’re don’t really have a reason to use Org in the first place, unfortunatly.

@cobblepot Could you please expand on this point?