Scrivener for Technical Writers

Scrivener
,
1

Is anyone using Scrivener to do professional technical writing, especially for software documentation (and, yes, I mean besides that the Scrivener manual was probably written with it)?

I will soon start a new technical writing job where the other writers mainly use FrameMaker. I am fairly attached to Scrivener and enjoy using it. I would like to use Scrivener for drafting, so I wanted to hear from anyone who has tried to work with Scrivener and FrameMaker both.

Thanks.

(Note: I will be running FrameMaker in a virtual machine, as Adobe stopped releasing it for Mac long ago.)

2

Wow, I used to use FrameMaker on the Mac several years ago and loved it!

I now use Scrivener for all my “project” writing: which mainly means developing websites (so all my content is written in Multimarkdown in Scrivener then ultimately translated into HTML). I’m taking a guess that Scrivener would be able to do much of the work needed. If the technical writing involves lots of images (e.g. screenshots of software) and needs to be auto-numbered, then Scrivener may not be the best product for doing this part of things. But if I remember correctly this level of detail is easy enough to add into FrameMaker. (I’m assuming FrameMaker will be where the final PDF or document product will be cooked.)

If I were in your shoes I’d definitely make Scrivener my first choice. But things might change depending on the folks you work with on the project, and the exact format they need to receive content from you.

Sorry I can’t provide more useful details, but I love Scrivener for projects other than typical novel or non-fiction writing. Depending on the details of what’s needed, and in what format, from you then you might want to consider teaming up with the Marked2 app: but this is primarily useful if you need to end up writing via Markdown or Multimarkdown. If your software documentation is going to end up online rather than a PDF, then Marked2 could prove to be a serious complementary tool to Scrivener.

3

Thank you.

This group seems to all work pretty independently, so I think I can just use FrameMaker at the end for formatting. I was looking at writing in Markdown, for sure.

4

I do technical writing everyday, and have done it first with Word for Mac (4, 5.1), then with PageMaker, then again with FrameMaker. When FrameMaker for Mac was demised I started using the Windows version in Parallels and VirtualBox. The Windows version of FrameMaker is far from the one for Mac, with less and less logical shortcuts, several bugs, bad PDF output. In addition, entering characters out of the stardard English set is a hassle (I usually write them in Mac, and copy/paste them in Windows).

Recently, I’ve started switching to InDesign. InDesign (CS6) is good with shorter works, but is proving awful with my typical long book (between 300 and 500 A4-format pages, split into 100~150-page chapters). Cross-references and change in pagination forcing background opening of target files, the spinning ball is your most seen working companion. Even typing a few characters may (and probably will) make it appear.

One of the solutions I tried was writing everything in an external text editor, then do the final layout in InDesign. Unfortunately, my proofreaders pretend to see the finished work early, compliant with the printed version (we are still doing printed books). So, I have to switch to InDesign very soon. I hope this will come to an end when I can move my work to a liquid format, and abandon the book form (frankly a bit obsolete for modern technical references).

As for the external editor, I tried first with Scrivener. There should be a report somewhere in the forum, but I cannot locate it. Working in Scrivener was great, but then there were two major problems for interfacing with InDesign:

  • no paragraph and character styles (for RTF exchange);
  • no preview for markdown (for exchange in MD).

As for the first issue, one could think to go through Nisus, and use its advanced selection features to apply paragraph and character styles to text formatted with Scrivener’s Formatting Presets. However, this proved to be a long and troublesome process.

Previews of markdowns could be done with an external app like Marked, but working by looking my typed text with the left eye, the formatting preview with the right one, is not my preferred solution. I’m thinking to try with Ulysses III, but even in this case I’m not sure all required characters styles could be simulated with markdown.

The return of FrameMaker for Mac, or a (not likely) improvement of InDesign long document features would be a headache-solver for technical writers.

I should also refer to Flare (also under Windows only), but I’m not happy of its page layout features and general look. It seems to be conceived for old-school manuals and Windows help, while I’m leaning toward more modern supports.

Paolo

5

I realise the last post was 9 years ago. Anyway i came here and downloaded Scrivener because i am interested in using it for generating technical manuals. I’ve been a technical writer and technical trainer for 12 years or more so this is my day job. But i also write software for personal use as well and often have to create user manuals, design documents etc. I’m working on a big software project right now and have a huge number of notes in Obsidian. I read an article on the forum there about how to use Obsidian, Zotero and Scrivener combined and decided to give it a try. My first Scrivener project is a book i am writing about how to develop a very complex software system. However i did not find any obvious templates dedicated to technical publications, just the non-fiction template. A google search didn’t bring up any other possibilities either, so i have come to this forum to see if there is anything. After searching i found this post so just wanted to say hello!

1 Like
6

Hello and welcome.

I think your next move should be to look in the Markdown & Latex forum. There are many threads concerning the use of workflows using Pandoc, Latex, Quarto and Typst to produce academic and technical output (I myself am just dipping my toes into that water as a project to keep my elderly brain active, not because I have any pressing need for such a workflow). There are contributors there who really know the ropes on them.

:smiley:

Mark

2 Likes
7

I would take a look at these threads, for more specifics on how Scrivener is best used in this context:

  • Scrivener and technical manuals: covers and discusses a broad range of tools, from LaTeX, to InDesign to Quarto and a few others. Scrivener is quite adept at working with all of these systems, so long as you start from the right place (i.e. not treating it like a word processor, but more like a Markdown writing platform).

  • Speaking more specifically on LaTeX—which can be approached much more directly as another plain-text syntax, rather than using Markdown—here are some thoughts on that debate, but it’s worth noting that’s a little dated, as these days we have an official non-fiction LaTeX template in the software, which fully demonstrates a number of the concepts spoken of in that post. For those where LaTeX is the one and only end-game, this can often be the best approach. Markdown is by necessity an abstraction, and to get around its limitations one needs to employ tactics to do so (more on that below, you absolutely can and make it beautiful in Scrivener).

    The “General Non-Fiction” template is more… I would say for biographies, topical books and the like. You will on the whole find very little in Scrivener’s basic feature set that supports the needs of a technical writer, and this template is rooted entirely in that more basic approach: fonts and styles basically, not even real captions you can cross-ref to, much less easily build a list of tables/figures etc. from.

  • Definitely search the Markdown & LaTeX category for Quarto. This is an up-and-coming system that promises to be a one-stop Markdown-based publication system, specifically for those in the sciences and technical writing fields. Scrivener is quite suitable as a starting point for production there, as it can produce Pandoc-compliant output, which is what Quarto needs. There are already some fantastic project templates and workflows documented by the user base. While Pandoc is good on its own, if I needed a DOCX workflow I would very much consider Quarto over it, because it plugs some gaps about DOCX output I don’t care for (like captions that are much as limited as Scrivener’s styled text with baked in numbering).

  • Also search for Scrivomatic, by another forum member, which aims to streamline and fully automate Scrivener+Pandoc processing, with an emphasis on academic, sciences and technical needs.

I believe I explain the basics of what makes Scrivener tick as a syntax content generating platform in some of those links, but to put it more succinctly: what sets it apart from many other systems is that it lets you build your own “front end”, making the text easier to work with and edit around ultimately. For a bit more on what that means, at a practical level, here is a discussion that goes a bit into that concept, which shows a demonstration of how the user manual project for Scrivener employs styles and section layouts to generate syntax—meaning as the one working with that text, I don’t ever have to see it because the compiler inserts all of that for me. The “front end” for a menu label is some blue text in the text editor.

Some take that principle all the way to its end conclusion, and do not even see a bit of Markdown (or other syntax, again, Scrivener is flexible in what input you use, but I focus on that since Obsidian was mentioned, and it makes all kinds of sense to normalise the writing interface if you can). Some use the “Emphasis” style to insert asterisks around the marked text, for example. That is entirely a matter of taste with a program like this! You can go from 100% pure Markdown in the text editor (which makes for maximum cross-software compatibility when using external folder sync to use multiple tools on the same source, like Obsidian), to more like I do with a mix of whatever makes sense in the moment, to like I say, something that really looks a lot more like a rich text user’s project at first blush.

Hope that gives you some ideas at any rate! The big advantage of considering Markdown w/ Pandoc/Quarto in Scrivener is that your output options go from half a dozen or so with mediocre results, to this.

As a postscript, the Scrivener user manual project, while not a technical document per se, at least does employ a number of features of such a document. I referred to some of its techniques above, and this is where you can see them in action and in settings. Two caveats: (a) it still does not compile properly in the Windows version and (b) the source material is quite old (but that matters little for the technical implementation of it). You can compile it, but it won’t typeset because it produces malformed Markdown in some places, and a few other issues.

1 Like
8

Thank you. This is a lot to take in and most of it is is over my head right now but I will persevere.

9

At this point in your thinking, best to distinguish creating/writing your document from the subsequent (and certainly less important than creating/writing when the document is not created or written) task of publishing it. This is often conflated with talk of LaTex, Pandoc, etc. There is nothing really special about technical writing but for things like tables, equations, figures, indexes, table of contents, perhaps numbering for chapters/sections, etc. versus novels which typically have none of that. Scrivener can handle both.

10

Just expanding on @rms’s comment, the entire point of Scrivener’s Compile command is to separate the writing and formatting tasks. That’s in contrast to something like Word, where defining a stylesheet up front is fairly important.

As you encounter elements that you expect will need special formatting – headings, tables, whatever – create and assign styles for them. It doesn’t matter (right now) what the styles look like, you’re just labeling the text for future reference.

As you have time and motivation, experiment with ways to use the Compile command to manipulate those styles. You should be able to produce either DOCX or Markdown/LaTeX output from the same source text.