In search of the perfect (or perfectly adequate) writing tool

Everyone who uses tools for a living loves their tools. And has strong opinions about them. Most programmers are happy to talk about their favorite coding languages and development tools, for example. For tech writers, we get to argue about content management systems, authoring tools, authoring formats, documentation structure…And that’s after we’ve battled over grammar, font choice, and glossary terms. Seriously: Glossary battles are the worst.

Now I find myself needing to change my writing process, and probably adding a tool or two to my workflow. Oh joy.

What I’m doing now

This is where some of you are going to wail, moan, and gnash your teeth in horror, scorn, and general “I can’t believe he’s doing it so wrong”-ness. My process is:

  1. Go to my knowledge center.
  2. Open an existing topic, or add a new one.
  3. Type. Right there, in the editor. It’s a WYSIWYG editor, even.
  4. Import images, add links, make sure the headings make sense.
  5. Save.

Horrific, I know. But it’s also fast, easy, and means that the process is very, very fast.

To be perfectly honest, I create new topics in a hidden Draft folder, and then ask the appropriate SME to review the content. And based on Tom Johnson’s suggestion, I’ve been changing my process of writing longer topics to do the writing in Google Docs, and have the reviewers check it there before I move it to the knowledge center.

But for small topics or minor edits, that list encompasses my writing and publishing process.

And it’s wonderful

I don’t have to validate the structure of the docs against any structural constraints other than my own. I don’t have to pass it through a formal word choice list, or any other draconian measures routinely imposed by standards groups on poor, suffering writers.

Obviously, this is possible because of two reasons:

  1. I’m in charge of the documentation.
  2. I’m the only writer.

I hold the standards within my own head (“try to write stuff that’s useful and makes sense”), so there’s the obvious problem of scaling this solution to more than one writer. In the past, I’ve done this by hiring really competent writers; while I don’t plan to change that part of the process, I also want to minimize the amount of work they have to do to get up to speed.

Here’s why that won’t work

Or “here’s why that won’t work well”: It works when I’m documenting a single product. Or if I document multiple products that don’t share content. But it doesn’t scale well if I have to document multiple products that do share content. In that case, I’ll need to do a lot of cutting and pasting. I’ve done that before, enough that I don’t trust myself to do it too often.

On the other hand, my requirements aren’t too complex.

And here’s what would work

I need some tool that’s inexpensive to purchase, install, configure, and maintain. “Inexpensive” in terms of money and time, since I don’t have a large budget of either. Fortunately, I just need to output to HTML. PDF output would be nice just in case anyone asks, but it’s not a requirement.

My existing content can be exported to HTML. I’m not stuck with any proprietary formats, or even something common-yet-messy, like Word.

So I need something that allows for content reuse, and tracks and manages those pieces of content, and makes sure that those pieces are in sync with each other.

I’d love something that would let me set up a structure, write, export to that structure, and then would keep everything under control, even when I decide that the original structure is stupid and need to rebuild it three days later.

And a big nice-to-have

Support for collaborative authoring. Which requires a non-arcane syntax, because even a small barrier to entry is enough to keep the potential authors away.

Basically, anything more complex than markdown isn’t going to work. When you’re asking someone to do you a favor by helping you create documentation, they won’t be eager to learn a documentation syntax that they’ll use once a month, at most.

And, yes, I realize that they’re doing your company a favor by documenting the information that’s otherwise stuck in their heads, but most people are going to look at their schedules and consider this just one more request on an already too-long list.

Next steps

So I’ve put together a list of requests. Now I need to figure out what tools are out there (I know that the answer is “a lot”), and match them to that list.

I’m just a little afraid that I’m asking for a unicorn, and the answer will be “Sounds great; feel like coding it yourself?”

Advertisements

15 thoughts on “In search of the perfect (or perfectly adequate) writing tool

  1. I have been thinking about this exact problem and will probably expand my thoughts in a post. One quick solution might be to use Flare. It does everything you need here. (As would Robohelp or Author-it Cloud, I think.) I wish I had a better response. So many of the interesting things people are doing on the web seem to be through custom-built sites. You could install a web-based CMS of some kind, but it would lack the tracking of re-used content.

    1. Flare is good, but expensive. It’s also not friendly for collaboration, unless I’m mistaken (or they’ve added some new features).

      I can see why people are going for custom-built solutions. The existing tools aren’t fulfilling their needs, and different companies have different needs, making it difficult for tool makers to create something that has wide appeal.

      But since I don’t need to create books, I don’t need heavy desktop publishing tools. One thing I can look at is a way to close the gap with engineering, and learn more about their tools.

  2. Neal, if you want to do content reuse, I would recommend going to XML, either DITA or Docbook. And if decide to use either of those frameworks, I would recommend that you use Oxygen XML Editor (http://www.oxygenxml.com/).

    Oxygen comes with the ability to generate webhelp, HTML, PDF, and more. It’s pretty cheap and very powerful. It also hooks into some source repositories and a couple of CMS frameworks.

    1. I need to look at Oxygen again. I used it a few years ago and wasn’t impressed by its (lack of) usability.

      I’m not a fan of DITA, and if nothing else it introduces arcane syntax that’s unfriendly to non-experts. Since I only want to tag sections for reuse, and not every little component, it’s also overkill.

      So I’m looking for a genius system that allows for a lot of flexibility and is easy to use. Odd that I haven’t found that yet!

  3. Mediawiki is a good platform if you really need collaboration. It’s one of my favorite tools.

    If you go the DITA route, I second the recommendation in using Oxygen. But as you pointed out, I doubt putting everything into DITA XML will facilitate collaboration.

    I do like Drupal quite a bit — more than I anticipated. Although there are simple platforms for managing content, it’s nice to have one that is robust enough to do so much.

  4. If collaboration is a primary consideration, then Tom’s recommendation of a wiki is a great idea. (That’s not to say it’s not a great idea in and or itself–no slight intended, Tom.)

    You might also look into Sphinx (http://sphinx-doc.org/), which is easier than DITA (it uses markdown) and has built-in transforms for PDF and HTML output. It’s very easy to use, free, and you find free hosting for collaboration (http://readthedocs.org/). It also allows for content reuse.

  5. Thanks for the suggestions!

    Tom knows well that I like wikis: http://idratherbewriting.com/2012/04/14/guest-post-why-i-love-wikis/

    In my overly-summarized list, I failed to include another requirement: I don’t want another site. I’m already maintaining a customer support/knowledge center site, and I want a tool that outputs to HTML so I can easily import it into that. But even that has it’s own challenges.

    Although having an wiki where we do editing and staging might be an idea. I’m now running an internal Google Sites…er…site, for our team to use to share info. It’s working pretty well, but it’s not really designed for content reuse.

    Ok, so I need to look at Oxygen, Sphinx (the first I heard of it was on your blog, Scot), and Drupal. I’ve looked at Drupal, but discounted it in favor of Mindtouch. But I was also evaluating it for different requirements.

    In the long run, I’m want to push as much help into the product as possible. For that, a tool that supports HTML export is probably still going to be the most useful option.

  6. The easy solution for you is called “static site generators”. Depending on if you need to generate small docu for one project or rather big portal for multiple projects, I recomend jekyll or docpad. As most of you SMEs are most likely developers, you can keep your project docu on some git repository, for free on github but maybe you already use something internally for version controlling. I bet your SMEs would love to create docs in simple markdown, update the project’s doku on some repository with git. For kyll and docpad you have many sample free projects out there that you can reuse and fit to your needs. Sphinx is not that easy if you compare it with them. I can talk about it for hours as we are starting using docpad, we tried jekyll to and we see how powerful solution it is. Even more, if you connect your repository where you keep your project docu with some continous integration tool, you might do a nice automation for building of your docu.

      1. When I showed my devs this approach, they were very happy that they can edit documentation together with their code in one place, beloved IDE. I expect that this solution will also increase the amount and quality of docs provided by devs. I’m planning to write some series of blog posts about the topic, but that will take some time

  7. Interesting post, Neil. We have a similar (actually, the exact same) need at my company. And we’re currently in the market for a new tool. We use Flare, but it’s a bulky desktop tool that doesn’t allow for great collaboration. We’re looking for something easy, produces HTML output, and allows us to spend our time writing and not configuring things on the back end or troubleshooting errors. I’d love to hear what you end up with!

  8. This is a vendor post
    **************************
    Did you already hear about HelpServer?
    HelpServer is a web-based team-authoring solution geared towards documentation and help.
    The nice thing about HelpServer is that authors can work with a client authoring tool (=workbench), which retrieves/save content from/to a database on a web server. This can be either your web server or one of our web servers since HelpServer is also available as SaaS.
    HelpServer comes with an easy to use WYSIWYG editor and all content that is contributed is stored in a database on a web server. Images or any other files can be uploaded by means of drag and drop, and can be reused by your authoring team.
    Your authors can reuse content objects like for example topics (in HS terminology: only one object will exist in the database and can be reused/referenced in/from different places within your content hierarchy). Another scenario is that your authors can create new separate instances based on existing content objects (=like Xeroxing a paper and then start writing on it).
    The workbench (=the authoring tool) is nice to work in because your authors will feel like they are working with client software (although content is retrieved from / or stored in the database on the server when needed, you actually do the authoring in a client workbench which is installed on the client computers of the authors). The client workbench can be installed on Windows and Macintosh computers.
    When content is ready-to-go, authors can publish content. With HelpServer publishing is NOT about creating static files, as most other help authoring tools do, no instead it is turning a switch in the database to make your content in real time accessible by your target audience. In fact this is an important difference. Because if your team tomorrow needs to change a few topics, you afterwards do not need to publish the entire shebang again, no you only need to publish the topics that have changed. The result is that your target audience will always access the most recent published version of your content via a front-end web-portal (which comes of the shelf with HelpServer) and from this web portal can browse, search, and print content to PDF.
    HelpServer is web- and server-based. This means HelpServer will listen to incoming requests (URLs that are launched and hit the HelpServer server), on the server-side the needed content is retrieved from the database and the content is rendered to the browser in real time.
    Next to delivering dynamic content in true real time via the web, your authoring team can also export content from the database to popular file formats for offline delivery (HTML + PDF + Translation XML + XML).
    If interested visit http://www.helpserver.eu and get started with a free trial or contact me, I would be happy to introduce you to HelpServer during a WebEx meeting.

Comments are closed.