Document the logic of sibling & child generation


I would just like to recommend that it be clearly outlined in the documentation for the Mac app, and also the iOS app, how the sibling and child logic works. That is, that it be very briefly, but prominently, explained in which situations creating a new document or folder will create it as child, and when it will create it as a sibling.

I’ve used Scrivener for several months now and it never dawned on me just from usage what the logic was. I did see the option in the Preferences to always create siblings, which I left unchecked, because to me what was logical was to create children. So I was always confused and slightly annoyed whenever I created new documents that they always seemed to generate as siblings (now I know it’s because I use a lot of sub-documents).

It took surfing this forum and reading this post (e.g. “The trick to remember is that creating a new document or group when the selection is on a Group will always create a child. When the selection is on a Document, it will create a sibling.”) to realize what the logic is.

Now that I now what the logic is, it all makes sense. :slight_smile:

This is documented under the commands for new files and new folders, page 462 in the menu appendix. Every menu command is discussed briefly, along with tips on usage like this, so if you’ve not checked it out yet or have questions about a particular command, that’s a good place to start.

Thanks for that reference! When I say “prominently,” I think this behavior should be documented in the interactive tutorial and in the part of the manual that introduces the binder–specifically, on page 65 or 66, section 7.1.2 “Scrivener as an Outliner” and/or 7.1.3 “Folders are Files are Folders.”

I like Scrivener and it’s the best software I’ve found for writing a book with a lot of links in it. That said, it can be a little obtuse! This issue is one example.

It’s a minor issue, so minor that I shrugged and kept writing every time it happened (until today)…but it kept happening, because I couldn’t figure it out, and I think most people are not going to be able to figure it out either, because:

  • it’s a minor problem, so they will live with it like I did, and not go digging in forums for the solution…so it will keep bugging them too
  • it’s hard to find the solution (have to go digging online in the forums or perhaps use the right key words to find page 462 of the appendix or have the patience to read all the way through the appendix)
  • it’s not obvious behavior. You would think a menu or context menu command of New Text (or New Folder) would have the same behavior no matter where you invoked the command. That is how other outliners behave. They have separate commands for creating children and creating siblings and these separate commands work the same no matter where you invoke them. For instance, see Tree 2, mempad (Windows software), Freeplane (mind mapping software), among others.

As far as I know, Scrivener is unique in that one command (New Text/Folder) will create either a child or a sibling depending on whether a Text or a Folder is focused. For this reason, this context-sensitivity–how it works–should be explained briefly when first introducing the Binder and/or when first introducing making new files/folders in the Binder.

Unless people are able to figure it out just from usage, unlike me! That could be the case. I kinda doubt it though, for most people.

That’s my opinion, anyhow. :slight_smile:

Yeah it’s something that has had some discussion over the years but not much—and for an outliner it is a bit unique, you are right about that (but then most outliners do not have a folder/file model, so we don’t exactly have a lot of precedent to work from). There is in fact one other variation of behaviour not mentioned where if you create a new folder with one of the two special root folders selected (Draft & Research), then the folder will be created as a child instead of a sibling like in all other cases when selecting a folder and creating a new one.

Oh yes, there is one other very obscure exception: if a group has a default subdocument template assigned to it (like the character sheet folder in some of our built-in templates), and if that default template so happens to be a folder, then in that case the new folder will be a child—otherwise it would be a nonsensical assignment as a sibling to a group would no longer be subdocument and therefore not be inheriting any default template type.

I’d like to think that in most cases the diverse behaviours may not work as expected, if you try to think it out logically, but expected rather in a way that doesn’t often get noticed—in that it does what you’d want in most cases. Most of the time if you’re using folders for larger groups like parts or chapters, you would want to make a new grouping on that same level, so the folders-as-siblings behaviour works without comment. Most of the time if you select Draft and make a new folder, you want a new section in the Draft—not outside of the Draft (I think if it were that way we’d have a lot more people composing their entire book on level 0 and wondering why nothing compiles!). Again most of the time when you select a folder and hit Return to make a new file (or Cmd-N, or clicking a button, etc.) you want a new chunk of text in that folder, rather than a chunk of text at the same level as the folder. You make a new folder and then what, you want a new file, and most likely you want that file in the folder.

So does it follow a strictly logical pure outline approach where every new thing is a sibling (or maybe child) no matter what? No—but I think most people do not actually want that, evidenced by this being a fairly rare point of conversation around here. I think it’s also good to consider that most people do not have much familiarity with outlining style software at all—that’s why I have that chapter in the user manual going over the absolute basics of the tree model, because for many people this is their first exposure to the concept of having an indented content tree that isn’t embedded in the text editor (like Word).

By the way—if you do want a more strictly logical approach then you can tick the Always create new items as siblings option in the Navigation preference pane. Now there is no more assumption, everything will always be made on the same level no matter what you select and no matter what type of thing you are creating. (Er, now that I say that, there is one exception (ha), again the aforementioned root folders force a child no matter what.)

You’re in luck though, as I’m currently rewriting the manual for the next big update—getting ideas like this in is something I have all of the time in the world for right now. :laughing:

Awesome! Yeah, my thought is that it deserves a very brief mention early in the documentation/tutorial. A brief aside, really.

I should explain that the reason the behavior didn’t work the way I expected is because I am writing a piece of interactive fiction–where the narrative is not a single thread but several branches–and depending on the reader’s choices, they will follow different narrative branches, sub-branches, sub-sub-branches, etc. So I would have a Text from which a reader could go on certain narrative paths but not others, so it made sense to group tho applicable narrative Texts as children underneath that original Text.

So I have a lot of Texts with child Texts underneath them. And child-child Texts underneath those. Etc. And I have relatively few Folders.

So I didn’t recognize why my new Texts were not being generated as children. I didn’t recognize that there was a pattern/reason.

But honestly the pattern/reason does make sense, like you said! It makes sense to me now, that new “pages” if you will, would be in the same “stack” as other pages. For people writing regular books and such, I don’t think they’ll run into this issue. But for anyone else using a lot of sub-Texts for whatever reason (interactive fiction or otherwise), I think they might run into this hiccup.

Now that I know, it’s super-easy to remember/internalize.

By the way, if you’re working the way I think you are from your description, you might prefer the Navigation preference to “Treat all documents with subdocuments as folders”. That will cause file stacks to act like folders in terms of how items are added to them, as well as what happens when you click on them—they will use the group view mode by default (like corkboard) instead of going straight to the file editor. Might not, but it could be worth a try. It’s a setting I use and I also make heavy use of text groups over folders (the latter of which I use sparingly for major sections).

I’ll try it out, thanks! I think either behavior will be fine at this point. :slight_smile: