Retrograde tooling

We've reached a tipping point in technical writing, and we need to deal with it.

The future is not going to involve producing documents, it's going to be producing seamlessly integrated content in and around products, and that means we need to change our expectations around tooling. This is going to hurt, but hopefully in the good way.

When I started writing, I learned FrameMaker. It was amazing. It had 20 years of history even at that point, and you could do anything with it. Equations, printer's crop marks, swapping text blocks in and out automatically, producing print, PDF, and help files from the same file, complete with changing cross-references. Using Frame was as much art and science, and there were key commands that were transmitted through the mailing list, by word of mouth, because they were no longer in the official documentation. It had a learning curve like a brick wall, but once you got through it, you were driving an unstoppable tank that could roll over any problem.

After 15 years, including occasional painful exposures to trying to do professional documentation in Microsoft Word, we got a new, hot product called MadCap Flare. It was like FrameMaker had been reincarnated for the web. It was easier to use, had integrations for localization, CSS, HTML5. It was shiny and beautiful and powerful. I could still do conditional text, referenced text blocks, and single-sourcing.

I haven't used a technical writing tool like that in 18 months, and I think it will happen less and less often.

The rise of Software as a Service and app culture is driving us away from a world of User Guides and Admin Guides and Installation Guides. Instead of CDs with instructions, we expect pop-up help bubbles and interfaces that guide us through what we should be doing. This makes a lot of sense, since we are all experiencing individualized experiences based on our bandwidth, app collisions, needs, and licensing structures. Writing a document that includes all that would be extremely difficult with the old tools, and we don't have the old tools anymore.

We don't have them because without the need to produce Official Documentation, we've reduced and eliminated technical writing departments and jobs. We're moving a lot of that work into User Experience, and we are asking the writers that remain to serve as a clearinghouse for content produced by developers. Instead of a journalism model, where we interviewed developers or were embedded on the team, we are now working as aggregators, taking content from many sources and getting it ready to distribute. Or there just isn't a writer, and publishing is much more ad hoc.

FrameMaker and Madcap Flare cost between $1000 and $2000 per seat license. That's not something you're going to buy for someone who is doing it part time. And it's hard to port data in and out of them, because of all the metatext and compiled information that's attached to them in the tools. It's a database, not a set of flat files. Or more accurately, it's a compiled binary – not the program, the document. So a writer using one of these tools would be a hard gating function on a team's ability to publish their own writing. It would look great, but you'd have a single point of failure.

Instead, we've been moving toward having technical writers use tools that are freely accessible to developers. Markdown that is compiled with readthedocs or readme.io or some other blunt-force tool to create a page with a table of contents and some minimal linking. The advantage of this is that everyone can read, write, and access the docs. The downside, which is mostly only visible to technical writers, is that we have lost enormous richness in treating our documentation as an object-oriented compiled object.

Here are some examples of things that I either can't do or are very difficult:

• Conditional text – different output text based on flags set on the whole document.
• White-labeling – configuring my documents so secondary organizations could brand them themselves
• Smart localization – Doing bulk localization based on common words and phrases, reducing translation time and cost
• Write once/publish many – having a master document that can produce help, web pages, print, and in-product assistance
• Context-sensitive help tied to the page the user is on
• Tables – Markdown, why are you so bad at this?
• Sophisticated layouts – headers, footers, breadcrumbs, inset images and text blocks
• Automatic ingestion and formatting of other file formats
• Includes, referenced text, inserted files – think libraries

That's a lot to lose! Sometimes I feel like writing in Markdown is like making Gutenberg to give up on the printing press and presenting him with and angry goose and a curly sheepskin.

However, it's not going to do me any good to bemoan the lost glories of the tech writing tools Roman Age, because we are in the Dark Ages now, and we just have to move forward to the Enlightenment as soon as we can.

….I was going to make a comparison table for you here in WordPress, but that's not a thing. My point exactly.

Anyway, here's what I think we could start using to regain some of our lost abilities:

CSS – Might be able to help with layouts, HTML5 support, tables, and white-labeling

Feature flags – conditional text, write once/publish many, and ingestion

HTML – (stop laughing. HTML is much more fully featured than Markdown) tables, context-sensitive help, includes

De-duplication – smart localization, includes

Javascript, PHP, etc – ingestion and formatting, menuing, navigation, breadcrumbs

Wow, that's a lot to learn. On the other hand, I heard a talk last week that included a 5 minute list of everything you "needed" to know to become a useful devops engineer, so I guess it's not bad compared to that. It is a pretty intimidating list for people who got into technical writing because they like writing, rather than because they like technology. It's not that writers can't learn tech – obviously we can, because we learned those old tools. It's that there is only the beginning of a community around this new renaissance writing, and no one tool that we can teach juniors.

I fell into tech writing because I took an English literature class with a very avant-garde professor who taught us hand-coded HTML (because 1995). That was the key that opened the door for me. But what key is out there now?

I hope Corilla continues to learn and grow and thrive – they could add in many of these features or already have them.

I hope Read the Docs gets enough funding to hire someone who is a technical writer as well as a coder, because they are missing some significant use cases, but they are also an industry standard.

I hope the OpenAPI standard and Swagger make it more possible and easier to expand their powerful use of code snippets into non-API documentation, because they are coming at the problem a new way and it involves a lot of the hypertextuality I'm looking for.

I hope Confluence realizes that they are setting people up to create unusable wikis because they default to an older, siloed world.

And honestly, I hope SharePoint spontaneously combusts, because that is TERRIBLE.

This post was originally published on heidiwaterhouse.com