Technical Writing Software Recommendation Needed

Why do you assume the OP is operating in a corporate environment? And why assume that it is going to be technical documentation? Medicine involves much more than that – if you embrace the bio-psycho-social model.

It is been a while since I used XML (Docbook) as part of a writing project. If I recall correctly, XML applies specifically to structural and typesetting semantics, not writing.

I think @rkaplan has tool selection flexibility or he would not have asked for suggestions. I am curious though about what corporations require their people to use for technical medical writing on Mac. I do not personally know too many businesses that do much technical medical writing.

An advantage of something like Scrivener would be that you are free separate the writing from the typesetting. There would be nothing preventing you from producing Docbook copy if that was required. That is part of why I use pandoc markdown as my source in Scrivener.

Here are the direct transformations available using pandoc.

Didn’t want to offend anyone. Have been in the “visual” camp a long time - tried to convince my company to use latex2rtf as their HAT to compile Windows help files from the rtf and beautiful typeset PDF from the latex source as I started my career in 1997. We use markdown as an intermediate format if we need to get documents from colleagues not familiar with structured content. And yes, markdown is structured enough to embed it in, for example, dita xml document maps and even let it stay there so that the colleagues can edit their chapters without angle brackets.

But separating content from formatting was and is the main point to switch to a structured environment. That doesn’t mean you don’t have a nice “author view” rendered with CSS, the same CSS that is used to produce the PDF so in a way you get a kind of WYSIWYG.

That you can parse the documents before saving, even applying business rules using something like schematron (hey, this shortdesc is longer than the max. 50 words) is another cup of tea.

If I were a consultant or the mythic “lonsome writer” in a small business AND had the chance to choose tools that a I like I probably would have DT as my knowledge base, Scrivener for projects - perhaps with a little pandoc post processing to deliver the files my clients need.

To sum it up with old William S., “if we shadows have offended … gentles, do not reprehend” :slight_smile:

Yes, I can choose my software tools.

XML is used frequently in medical applications which legally require structure - such as labeling of prescription drugs or medical equipment. These constraints do not apply to more general medical reference texts, though XML is used as the primary database in the online Medline/Pubmed database, so it remains useful. For these reasons, I began my current project by trying out Framemaker, which strongly supports structured XML. However I concluded that this structure is too rigid for my application. On the other hand, the availability of HTML5 and Javascript in a WYSIWYG text editor in Madcap seems quite appealing. Scrivener is tempting since it is Mac-centric, but the incidental web capabilities of Madcap are quite notable.

I have tried Scrivener off and on for about 6 years, and have always found it too complicated for me. I am comfortable with complex software (hello I’m on the DT forum). I just find Scrivener does so much, even the tutorial is a slog. Also, it’s RTF - and I like to edit with plain text or markdown. I’m aware that there are people who use Markdown with Scrivener, but even googling “scrivener markdown” in 2020 shows a bunch of forum posts and articles from years ago… it just really doesn’t seem like an out-of-the-box thing. I want to be clear: I suspect that Scrivener can be an effective writing environment with Markdown, I’ve just repeatedly experienced it as an overwhelming, time-consuming rabbit hole.

Ulysses seems to me like a simple Scrivener, and it natively supports Markdown (or something very close to it, their own flavor of Markdown). As far as I can tell, it does the things that have people raving about Scrivener - writing in small chunks, rearranging them, compiling to multiple formats. I just find it way more accessible than Scrivener (although why they came up with their own Markdown-like thing is still a mystery to me… I suspect it’s because Ulysses was around before Markdown was ubiquitous).

My only beef with Ulysses is that it really only works by exporting one document at a time (and I have no idea how Scrivener works in this regard). So if I want to work on a collection of documents - say an abstract, and an outline, and the main document itself - then I need to export them all individually.

My other writing environment is Atom text editor + Jekyll blogging engine. That lets me write in plain markdown, and it produces HTML files. It’s nice because it automatically exports files any time I save them. The tradeoff is that I haven’t found anything that supports the “chunk” style writing that Scrivener and Ulysses do.

So for me, Ulysses is a great environment for drafts. I can do the chunk and organize thing, and when I’m happy with my draft, export the whole thing to Markdown and include it in a Jekyll site. I use the Jekyll site for formatting it exactly how I want, and then print to PDF.

A final note: I work as a computer programmer, and spend my whole day working with plain text editors. So for me, it’s markdown or bust - I just don’t have patience for RTF. My ideal environment (I think) would combine Ulysses’ chunk-ability with Jekyll’s processing. So ideally I could link a Ulysses group to a specific markdown file on disk. Or have the chunk-style writing directly in Atom. I haven’t found a way to do either one yet, so the draft-in-ulysses-and-export-to-jekyll-markdown works for me.

I’ve experimented a bit with emacs org-mode, and cool as it is, it appears to be way too much of a rabbit hole for me today :slight_smile:

1 Like

Hello Pat! :grinning:

You use Tinderbox, so I know you know about complex/perplexing software :wink:

I probably use a hundredth of what Scrivener does. One doesn’t have to go down the rabbit hole if one does not want to, and their forums show that there are some very non-computer-literate people who depend on Scrivener for their writing. It is an old saying that one person’s meat is another person’s poison, and there really seems to be no substitute for trying out different things and seeing what works for us. As to Ulysses, for example, I have tried it and hated it. We are all different.