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.