Another one of the periodical 'compiling is traumatic' threads

Scrivener Scrivener for macOS
1

… because it’s not an issue that’s going away or even changing much, from what I can see.

I’m honestly writing this in sorrow and hope. I’ve been using Scrivener off and on more or less since it came out of beta, on Mac, Windows and iPad, and I love the concept of writing stuff in chunks and moving it around. I also love being able to set up a writing environment on screen that doesn’t need to have anything to do with how it looks as output. The whole ‘compile’ deal, a bit like rendering video, or sending an audio mix to a single file, or outputting visuals in Photoshop to a jpg is a very good idea. And I do all those things often, with all their complexities and sometimes frustrations.

But compiling in Scrivener is still, after all these years, far more incomprehensible and agonising than using any of those.

I’ve spent the last three hours or so combing tutorials trying to work out what section styles are and how they relate to all the other stuff, and why some chunks of text weren’t appearing. I got somewhere roughly near what I wanted by trial and error, but I have no idea why what I’ve done works. Nobody’s doing the basic legwork of explaining, by establishing concepts then putting them together to show how they get users where they want to go. I know there are explanations, but they don’t make sense.

On the other threads like this, support staff appear and say ‘but, what, specifically don’t you understand?’.

It’s not one thing. It’s how the whole process is conceived of and (not) explained.

Firstly, in terms of the UI and the apparently arbitrary process for creating, essentially, a database report. It’s inconsistent and overcomplicated (and that’s coming from someone who used MS Access to do the same thing twenty years ago, and it made more sense).

Secondly, that means the explanations in the various videos and how-tos (and I’ve read/watched a fair number of them, both L&L and non L&L) are confused and contradictory. There’s no real map through the process. There are many, many details that are left unexplained.

Yes, compiling is powerful and therefore complicated, but that’s why writing support materials is a skilled job. It needs to lead people to their solution, not scatter key bits of information randomly and assume users will put the jigsaw of inferences together as though they’re in an escape room. The official manual is encyclopaedic but can’t be used to troubleshoot; it’s just not written that way. It’s all the more baffling because Keith used to be a teacher before he created Scrivener, so you’d think he’d get that there are ways teach people how to do things.

The failure isn’t my end: my work involves translating very complicated clinical science research into documents and other materials that laypeople can understand, amongst other things. That means my reading comprehension is good enough that I get well paid for it. I also teach at graduate level. L&L just isn’t doing a good job of explaining itself when it comes to compiling.

It shouldn’t take three hours to figure out the concepts behind a well designed bit of software, let alone three hours to not be able to figure them out. I’m geeky by nature and more than prepared to spend time fiddling with individual settings, but I’m not at a point where I have the faintest clue what any of it does. I don’t have the information to create hypotheses to use trial and error.

I’ve taught myself to use Premiere, Audition, Photoshop and a bunch of other programmes and Scrivener’s compile function might as well be in sanskrit by comparison. I can figure out most things in Adobe Premiere for example in maybe half an hour. Is compiling really that much more complicated?

I have the early adopter’s affection for Scrivener and I genuinely want it to be good. But ‘compile’ is awful, and L&L seem in denial about how bad it is. Please, please, rethink what you’re doing.

2

What happened since 2018?

3

Key concepts:

  1. A Section Type describes what an item in the Binder is. A chapter, a scene, an epigraph, whatever. Most projects will only use a few of these, and in many cases they can be assigned automatically.

  2. A Section Layout describes what an item looks like. Title? Single spaced, double spaced? Font? By design, the Section Layouts are part of the Compile Format, and exist separately from any particular text.

  3. The key step in Compiling a manuscript is to assign Section Types – which are a function of what you wrote – to Section Layouts, thereby determining what your output will look like.

  4. The simplest Format we supply is the “Default,” which essentially sends whatever you did in the Editor through to the output document. It’s a good choice if you just need something you can import into Word or another tool. Because it’s simple, it’s also a good starting point for your own experiments.

From there, you can add as much complexity as you want, all the way up to the Scrivener Manual. But the above four concepts should be enough to make sure your work isn’t “trapped.”

  1. If you have made extensive use of Styles in the Editor, and in particular if you have used a “body” Style, the Section Layouts will mostly appear to not work. This is intentional, and one of the reasons why we don’t recommend using a body Style. Read Section 24.5 in the manual, on Styles and the Compile command, before proceeding.
4 Likes
4

I just finished a Sanskrit course recently and I can tell you that it is a very scientically organized language.

3 Likes
5

As an analogy, I compare Scrivener’s compiler to building a ship in a bottle… and then smashing the bottle to get the ship out. Instead of laying out all the tools and components on a large work surface, and building the ship right in front of you, you are constrained by the neck of the bottle, and obliged to learn how to use strange and mysterious tools to complete the task.

Other than forcing the compile configuration into too small a windows, I think the problem is compounded by the abstraction behind it, which obviously makes sense to the developer – and can be learned – but is clearly not obvious to many other given the – as you say – periodic threads about it.

1 Like
6

Scrivener got updated and the compile system became powerful and way way more complicated.

7

Yes, I’ve put all this together from an evening of googling, watching videos, trying things semi-randomly, and piecing together inferences. I shouldn’t have to do this though - there should be a clear process spelled out by L&L support, and there isn’t.

Actually, your numbered points show the problem. They don’t explain how to apply anything, just define some abstractions. They don’t say ‘this is here, click on this and it will have this effect on the final document’. I know it’s complicated, but part of the developer’s job is to pin this down in their support. If it can’t be done with how the software is designed, maybe that bit of the software needs to be rethought.

And saying ‘professional software is complicated, suck it up’ is untrue, as well as being terrible customer service. I used many bits of specialised professional software. They take some time to tweak but the underlying concepts are clear. Scrivener’s compile is a continual ‘wtf’ experience.

The rest of Scrivener is also complicated, but it has a logic to it. Compile just makes no sense.

8

Still can’t understand it though. Also, I don’t want to have to do a course to understand one of the functions in a bit of text manipulation software.

9

I, too, feel your compile pain, as I’m sure many others do.

10

As described above but years ago I took the effort to set up a couple of formats I use. Then save and reuse with little tweaks. b

1 Like
11

I’m looking at the “Compiling the Draft” section of the Interactive Tutorial, and it walks through exactly that process.

Assign Section Layout A to Section Type B, using the button at the bottom center of the main Compile screen, to make the final document look like Layout A.

To change how Layout A looks, use the Section Layout editor.

I didn’t say that.
It is true that making something that looks like the Scrivener manual involves substantially more complexity than making a basic manuscript with chapter breaks and pagination. But that would be true in any software that you assigned to the task.

4 Likes
12

I’m looking at the “Compiling the Draft” section of the Interactive Tutorial, and it walks through exactly that process.

Assign Section Layout A to Section Type B, using the button at the bottom center of the main Compile screen, to make the final document look like Layout A.

To change how Layout A looks, use the Section Layout editor.

To you, it explains it, because your brain isn’t seeing the words ‘Section Layout’ and thinking 'hang on, which was that again? is the thing I set in the Project Settings menu hidden in another part of Scrivener entirely? Or is it one of those white boxes that I’m not really sure about? How do these things relate? Which thing am I meant to click on?'.

To those of use who are still trying to figure out what the constituent parts are, let alone what they do, that sentence truly reads like:

Assign the booglydonglydeep A to the offsquiggly B, using the button at the bottom center of the main diddlydum screen, to make the final document look like oofywallops.

You’re very used to the terminology because you work with it, so your brain doesn’t have to do the extra work to disentangle confusingly similar terms. The way to write this more clearly is take more time, use more words, spell everything out painfully.

And then

To change how Layout A looks, use the Section Layout editor.

… yes, but HOW?

Here’s a paragraph from that section in the interactive tutorial (one smallish section btw, in a huge document, which attempts to deal with one of the most complicated baffling things Scrivener does. But anyway).

At this point, the entire window changes to present you with a wealth of options. Here you can name the format, choose where to save it, create your own section layouts, determine the size of the printed page, set up page headers and footers, override styles, and much, much more. You have complete control over how your work will look when compiled.

But again, how? A lot of those things are far from obvious and it’s not explained.

A couple of paragraphs later:

We won’t go into all the details of creating your own Compile format here—the chances are that you will never need to create your own format and will only use the formats built into Scrivener. For now, it’s only important to know that you can create your own formats if you ever need to. Refer to the user manual (available from the Help menu) if you ever decide to get your fingers dirty (or just experiment—you can’t break anything!).

So is this detailed help or not? The manual takes us back to defining abstractions in terms of other abstractions territory.

As an example of the lack of detailed actual help, here’s a specific thing that I cannot find the answer to anywhere.

One of my sections is set purely to include the text from the document, which for some reason includes the title, even when the ‘title’ checkbox is unchecked. If I also have the <$title> placeholder in the Title Options, I get the title twice, so it’s not that. I’ve also set the compile formatting to over-ride the editor settings and that works for most of the text, but I can still set the title to bold in the editor (that’s the title which is included with the text whether I want it or not), and that bold formatting is carried through into the compiled output.

Somewhere, I assume, there are settings or a way to do achieve what I want, which is use compile so that the document title appears once, formatted as I want it which is different to how it appears in the editor. But the documentation gives no clue how I can achieve this, and the methods that would look like they work, just don’t.

I describe that as a concrete example of my frustrations, not to get an answer. But my main point is that one of the most complicated bits of Scrivener, and the bit that is at least 50% of the point of using it, is so confusing and under-documented that it’s unusable without insane amounts of study.

13

Section Types are described in the previous section of the Tutorial. (Which is, conveniently, named “Section Types.”)

Section Layouts are defined right there in the Tutorial section on Compiling.

• Each Compile format consists of a number of “section layouts”.
• Each section layout defines a number of settings that can be applied to a document in the Draft, such as whether the font face and size should be changed, whether there should be a page break before it, and so on.
• You apply a section layout to each section type in your project to tell Scrivener how to format your manuscript.

Chapter 24 in the manual, “The Compile Format Designer,” discusses each component of the Format editor in detail, with screenshots.

You are correct, the description in the Tutorial is very brief. And I agree that the idea that “most people won’t need to edit the Compile Format” is a bit overly optimistic. But Chapter 24 is nearly 80 pages long, with lots of screenshots and examples, and is organized exactly in parallel to the Format designer itself. “Under-documented” it is not.

In the Scrivener Editor, is the title present in the body text of the section? If so, that’s the problem: Scrivener has no way of knowing that a chunk of random body text is in fact the title. The only title that Scrivener is able to recognize as such is the Binder name of the item.

3 Likes
14

It’s essentially a description of all the variables, rather than ‘how tos’. That level of detail needs to be in the manual, but I think most people’s brains - most writer’s brains anyway - seize up at that this level of infodump. The manual’s written as though users will sit down and read it from beginning to end, rather than scan/search for terms, sideheadings, and pull out boxes that look like they might have relevant actionable information. It would be helpful to have some use cases and how to make common tweaks to them, halfway between ‘here are the presets’ and ‘here’s a huge list of every single variable’.

I figured out what was happening here, and my process kind of illustrates the wider documentation problem.

I noticed the binder titles were grey italic - in itself not a problem but I wondered if it was relevant, so I searched for ‘italic’ in the manual. Then I leafed through each of the 32 occurences of ‘italic’ till one of them was part of a paragraph about the binder and how Scrivener automatically generates titles based on other title-like text candidates - in this case first line of each document. My documents with italic binder titles were all from me splitting a longer document into multiple new ones, and Scrivener had created the titles each time I created a new document. However, I didn’t know Scrivener had done anything other than generate a static title based off the first line of a document. I wondered if, since it was doing things automatically, maybe it was re-autogenerating a new title each time I changed the first line of the document, which would result in the behaviour I was observing. Bit more reading and it turns out I can make the binder titles permanent by using non-obvious command in a submenu - it just says ‘set’, not ‘make permanent’. Doing that might stop the autogeneration every time I made a change, I thought. So I tried that, and, yep, I can change (and mostly delete) the first line in the document without it affecting the title as used by the binder and in the title bar of the document window.

(However the titles in the binder, even the ‘made permanent’ ones are still in grey italics. In order that they re-appear in the normal binder font, I have to physically retype the title. That last bit doesn’t feel right - now the titles are permanent, shouldn’t they become the usual binder font without retyping?)

So I achieved what I needed to, but it needed a fair degree of nerdy analysis, just to stop a title doubling up in compile.

I’m very aware that Scrivener now has so much going on that there must be probably thousands of potential scenarios of stuff like this getting … unpredictable. And manuals can’t error trap everything users will come up with, because we’re very inventive at discovering problems.

Maybe there’s just been too much feature-creep. Marketing and user pressure leads to incessantly adding new sparkliness and eventually it all gets out of hand. Making existing features work more smoothly and obviously would improve the software and user experience, but it’s a harder sell.

15

Over the years the product has been mostly unchanged. That stability has allowed many people to figure out how to compile. Perhaps you should consider hiring a professional to do it for you?

1 Like
16

Or just ask here. Preferably concrete questions. “I want to do B, but instead A happens. Why?” It’s not as satisfying as a good old rant, but I assume you want results.

(Image L&L decides right now to turn the Compiler upside down and rewrite everything – would you really want to wait for it? What if it’s all wrong again after this waiting period?)

1 Like
17

:roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes: :roll_eyes:

1 Like
19

If they are still in grey italics, then they aren’t permanent. I would have to look at the project to see what’s going on, though. You’re welcome to open a support ticket, here:
https://www.literatureandlatte.com/contact-us

That is, I would say, the fundamental issue underlying all of these threads. Not only does Scrivener offer thousands of potential combinations of settings, but authors themselves collude with publishers to demand thousands of different configurations. Beyond the very basics – which you’ll see replicated in our supplied Compile Formats – it’s nearly impossible to document every combination that users might want. That’s why the manual includes what you call “abstractions.” Understanding the underlying logic is the only way to make sense of all the possible combinations.

2 Likes
20

Love Scrivener but I too have great difficulty coming to grips with compile so I avoid it, apart from changing the output font. In relation to how features are described in documentation, I have noted for some years that the norm is to describe what a feature does, not how or when to use it. All very unsettling when first coming to use a new app. Hopefully the new L&L app will make ‘compiling’ much simpler and allow me to ditch the various post-compiling activities I use to get the output just as I want it to be.

1 Like