Technical Writing Software Recommendation Needed

This is somewhat off-topic from Devonthink though I suspect I am not alone in this group at pondering a book writing project in part using research sources/document I have collected in Devonthink. I posted in MPU also though I suspect that the DT3 users may have a more academic/writing inclination.

I am wondering what suggestions may be out there for technical (actually medical) writing software for the Mac.

I am planning to write a series of books in which I curate and discuss articles in the medical literature. The big-players I see are only PC-based: Adobe Framemaker and Madcap Flare; among those Madcap Flare seems to have a superior user interface and features, though it costs more than Framemaker. Either of these can publish simultaneously to responsive HTML5, PDF, and ePUB. Scrivener seems the closest match on the Mac and is much less expensive than either of those, but it has at best very limited HTML output capability.

Thus I suspect I will go with Madcap Flare and use Parallels. Is there instead some Mac-native solution that I am overlooking?

It may not be powerful enough for your needs but you might take a look at Ulysses.

I don’t know what complexities you are looking for in publishing to HTML, but Scrivener’s compile to HTML seems to have quite a number of options. Have you tried it out? (There is a trial period.) Scrivener is one of the best tools for long form writing.

1 Like

I wouldn’t hesitate: I would use Scrivener. There is nothing quite like it, and for long-form writing it is my opinion that it has no equal. I used it for an 80,000 word thesis, and I cannot imagine what it would have been like to try to write it using any other software.

The Scrivener forum is VERY helpful and has various regular and very knowledgeable contributors working in the sciences. There is a section on LaTeX which you might find interesting, and the contributor who goes by nontroppo has made many posts there, including systems using Pandoc for output. Another contributor who goes by lunk seems to be a scientist and makes a lot of contributions. Scrivener is a program that takes a while to get used to. There are options and complexities that are not apparent on a cursory glance.

Edit: this is the Scrivomatic system - https://github.com/iandol/scrivomatic

PS: I’ve been using Scrivener since about 2006. For me the most important feature is the ability to write in small chunks which can be moved around, combined, separated and viewed together or apart. It makes structuring a long piece so much easier. And in the work I do, the flow of information is critical for the reader’s understanding. Get things in the wrong order, and it is harder for them. I couldn’t write academic material using any other program.

5 Likes

I strongly second that! I’ve been using it for years on one project but only recently really got to grips with it and it is really good. The manual is heavy going at times but well worth a good read. The best place to start is with the introductory tutorial. Scrivener is an incredibly versatile piece of software.

Stephen

2 Likes

Thanks to all - good options to try and compare before making a final decision

It might be worth observing that Pandoc (https://pandoc.org) converts to all sorts of file formats, including HTML5 (so you could compile to rtf, docx, or something else, and convert to HTML5 that way).

Also worth looking at the Scrivener manual, which is written with Scrivener and can be downloaded as a Scrivener project file so that you can see how it was prepared: https://www.literatureandlatte.com/learn-and-support/user-guides (go down to the last item on the “Select Format” menu).

2 Likes

As @mbbntu states: Pandoc can be a really good and “lightweight” solution for the geeks among us. Ohh, wait …

I regularly use asciidoc to write lenghty documentations (mostly for web development projects and GDPR / Compliance reports with technical contents too). Asciidoc is somewhat like markdown but very different on the other hand.

Like markdown you write plain text in your editor of choice. But the with the likewise syntax you are able to write much more complex structures, include files for chapters into a global file, table of contents generation out of the box, predefined or self written templates / themes for different destination formats like pdf, html(5), epub and all pandoc offers.

1 Like

… pondering a book writing project in part using research sources/document I have collected in Devonthink. I posted in MPU also though I suspect that the DT3 users may have a more academic/writing inclination.

I am wondering what suggestions may be out there for technical (actually medical) writing software for the Mac.

As others have suggested, I would strongly recommend Scrivener.

Technical writing is still writing. I have never seen or used anything that I could recommend above Scrivener for writing. Scrivener is also more technical writing friendly than many other options. Typesetting is a challenge that is not unique to technical writers. That said, LaTeX is the best I have found for technical typesetting.

I use DEVONthink for knowledge management. I use Scrivener for writing, and LaTeX for typesetting. They fit together very well. Here is quick explanation of how.

DEVONthink

I create a new DEVONThink group for each writing project. I can then collect and replicate content into this group as needed. I take advantage of the DEVONthink item URLs in my Scrivener project.

Scrivener

I write in pandoc markdown format. Really this means that I do not worry much about formatting, but rather on writing and structure. Scrivener compiles my writing, with my own compiler customizations, from markdown to LaTeX, and them presents a preview in PDF. I plan to describe and share these customizations later but they are not necessary. I just prefer my workflow. I just can’t describe how much time Scrivener can save you when writing. The more I use it the more useful I find it.

Separating formatting and typesetting from writing is helpful because they are time consuming and really not necessary until the writing has been roughed out, edited, etc. Also you may use different typesetters with different publishers.

LaTeX

I have found no better way to typeset. Images, math, tables, and graphs are all challenging, and LaTeX meets the challenge. I find that longer writing projects benefit from LaTeX macros.

I create complicated graphics or graphs, with Tikz.

@mmynsted

Thank you for that detailed assessment.

Is there a way to Scrivener to designate reusable or recurring snippets of text which can be edited en masse with a change of the original?

That is a key feature most “technical writing” software offers, and I am not sure it can be accomplished in Scrivener.

Yes, there are multiple ways to do this depending on your precise need. The way that applies most directly to your question, and the simplest to use, would be replacements.

I use this mechanism to replace words, include graphics, tables, links, and entire files of content.
I use the other ways also, but they deserve more explanation.

Literature and Latte has a friendly community forum, Scrivener and other products forum, where I and others would be happy to provide more detail. I personally love talking about this stuff. Heh. :laughing:

You are also welcome to contact me directly.

1 Like

Does that mean that you write your “naked” text in Scrivener and then add the LaTeX commands/macros later (in a second version of the document?) or do you add the LaTeX commands/macros right at the start or is there some kind of automated process to get from Scrivener to LaTeX?
If that’s a dumb question, I apologize. I have no experience with Scrivener, I’m just curious about the integration of LaTeX. I know that lots of people love it, but I could never warm up to it (probably because I learned to typeset on a photo type setter and then later worked with DTP software).

1 Like

Scrivener provides a template. The template provides some documentation “built-in” and the template has the setups for creating LaTeX files. You “compile” to a .txt file that you load into a LaTeX editor. I use “texmaker”, but others available. You can add your own LaTeX things, but I’ve not done too much of that as I focus on writing and producing a great LaTeX-type PDF as my output without much fiddling. Lots of fiddling possible.

Try it for yourself.

Scrivener is very nice and the folks at Literature and Latte are worth supporting. There are things I wish they did differently, though.

If you write in an editor with good support for styles and style libraries, that’s the bulk of what a Scrivener compile does, isn’t it?

The perfect IDE for prose hasn’t been created. Scrivener is great, but has weirdness. The no-style style, the three different editors (main, copyholder, and quick reference), and the complexity of compile.

For now, I will continue to support L&L by keeping a paid license current, but I write in either Nisus or Mellel.

I am sure some use it that way. I do not.

@rmschne described templates and their relationship to the compile very well for my process.

The compile process for me, is what allows Scrivener to be a kind of writing force multiplier. I can make sweeping changes to what is included in the draft, its structure, its format, and other things that would require much more effort manually. If an editor or reviewer wants the copy in a particular format, no problem. I just compile differently. I know because I was happy with using VIM before I moved to Scrivener. There are times when I still use VIM with Scrivener. This is an advantage to my workflow, not something where the tool is lacking.

It can be complicated but one is not forced to use all the features. It is good that you found tools that fit well with your process.

Yep. That concept missed by many. Also what’s missed is the disconnect between WYSIWYG and production/printing.

Excellent Product. Like all high-end tools, needs practice.

1 Like

Good points, @rmschne and @mmynsted. I need to go back and give Scrivener a fair shake.

I know the company is run by talented people who hold their customers in high regard. Pretty cool when an individual effort grows and has such an enormous impact on the world.

1 Like

These are all good suggestions, but I am in this business 20+ years now, and you’ll likely end up in an environment that uses as structured source code format like DITA, Docbook, ASD1000, and then you’ll have to use an XML writing environment - and the best and most affordable, the one the CMS vendors build into their own solutions, is the Oxygen XML editor. So I would strongly suggest to take al look at this. - Of course, the people at L&L build their own manual using Scrivener and you can download and look at the sources and the transformation configurations, but I have never heard about anyone using Scrivener in a corporate environment producing technical documentation.

Scrivener will never will be allowed in many corp environments, probably. IT would never allow as they would have to “support”. Corporate worlds are much different than small business and independant writers. I’ve been in all those worlds. To be honest, glad to see the back of the Corporate world. Features of Scrivener best discussed in their terrific forum.

DEVONthink probably not also an IT favourite…

1 Like

Why do you feel this way?