Working with lots of images for a technical manual

Scrivener
,
1

I am writing a technical manual and there will be a lot of images. I am proposing to used a placeholder with link to the image.
I am looking for any tips on
a: doing this
b: subtitling the image with say chapter.section.image number

Also, I have tried “hard” naming the images e.g. Fig 21.3 for Chap 21 fig 3, but this gets messy should I reorder the chapters on say the corkboard.

Any tips appreciated.

2

Can you get away with using Pandoc or Quarto for the document production process, so that you can benefit from its better document generation capabilities and wider array of file formats? For example I use LaTeX, and I’ve never had to mess with anything so fiddly as managing numbering or links to them. I can instead very simply indicate which figure to refer to by its handle or name, and LaTeX automates and formats the rest from that (resulting in what you see in Scrivener’s own user manual, for example): the chapter.fignum style numbering itself on the caption, the caption formatting, the look-up from the cross-ref point to get that number, and the placement of the parenthetical hyperlink itself.

Here is Quarto’s documentation on figures. Just from skimming the ToC, I feel one could safely surmise that for technical writing this is going to be a far superior approach than trying to do everything in Scrivener itself, without any external help. It’s an okay tool for that, but that’s not its primary focus really (end format production), and I wouldn’t stress its auto-number system for much other than basic setups.

It’s worth considering that it pushes the problem you describe at the end, further down the workflow rather than solving it: the result is static text in the output, just as though you had typed it in. While some of Quarto/Pandoc’s output does likewise out of the box, I would say these are different things because in that case you can get very close to a finished document with them, one that will not require working with it extensively to get its formatting finalised. With Scrivener’s built-in word processor output on the other hand, it is very unlikely you will get to that point for technical writing, which means the .docx file or whatever will be in a primitive state, and likely go on to receive all future edits, without the original project being returned to. And that means static numbering is still a problem.

Here is a brief introduction to the idea of using Markdown in Scrivener. Our approach is to look at the process of automating or making easier the writing process with Markdown. While you can just drop raw .md straight into the editor and have it work fine (as described in that post), most will be using some combination of features (documented in Chapter 21 of the user manual PDF—which incidentally I did not number in Scrivener either) to go a bit beyond what can be done with that.

In short:

  • You don’t have to learn much about Markdown to get a lot of benefit back from it. In fact many don’t even write with it in the editor, and only learn the little bits they need to make the compiler do that for them (what it doesn’t do already, which is fairly comprehensive).
  • The integration can be so seamless that you would be producing final, or close to final quality documentation straight out of the compiler. To again use the user manual as an example, a document of that quality can be produced by clicking the compile button and nothing more. So we aren’t talking about not using Scrivener in other words, we’re talking about using it to produce better documents, by hooking it up directly to better converters.
3 Likes
3

Thanks for detailed reply. Its going to take me a while to work through your suggestions.

4

No worries, I didn’t explain much, because if some of that jargon means something to you, then the main message is that: yes, Scrivener supports integration with this technology.

If it’s all a wild new world, and you have never seen a tool like Obsidian or Ulysses or even iA Writer before, there may be some gaps in what I wrote. :slight_smile: Feel free to ask any questions, but we also have a whole Markdown & LaTeX forum here, which years of discussion on how to work with Scrivener this way. There you will tend to find a higher concentration of those using Scrivener for technical, sciences and academic work.

1 Like
5

Quarto is open source hence free,
Latex is free as it is only me as a single user
Which one should I focus on?

6

I would start with Quarto (documentation link), because it is (like Markdown and Scrivener) a bridge to other formats, whereas LaTeX is very specifically oriented toward print (or at least fixed layout on screen via PDF); it is an end point.

Quarto on the other hand can get you to Word, OpenOffice, ePub, presentations, web sites[1], other bridge formats, LaTeX too (and other higher-end typesetting), and lots more. From there, you have dozens of pathways and can work with anyone.

And if that looks promising, check out some Scrivener-specific discussions, including some fantastic templates from fellow users:

The main reason to target an end-format specifically, like LaTeX, is if you’re sure that will work for you and be all you need. There are of course advantages to doing so. Any bridge format is going to by necessity be an abstraction, or a generalisation of document formatting. With Quarto/Scrivener I can say, “put a footnote here, with this text”, with LaTeX I can say, “this footnote is special and should be in the margin, which will cause this page layout to have a wider margin than the rest of the book, and space the left edge of the footnote 18.842pts from the justified right margin, using 10pt font, and bold face on the anchor number”. That’s the difference in a nutshell, and that should also illustrate which of these is, by and large, a better tool for writing.

  1. When you are on their site, you are looking at an example of what it can do. ↩︎

4 Likes