What did I expect to get from conferences?

I really like Tom Johnson’s recent interview with Pawel Kowaluk, who is organizing a techcomm conference in Poland. After a much appreciated compliment, he explains that he’s trying to include topics that show how techcomm is a vital component of a company’s business practices, and not an afterthought, a bolted-on requirement that gets included because it’s just how things are done.

Which is what I’ve been trying to get to, and why I keep wandering around the point of why I think techcomm is important. And also why I’ve been frustrated when conferences become advertisements for tools or specific processes, without really explaining how we make the business case for our existence.

What did I expect to get from conferences?

To be honest, when I attended LavaCon, I was looking for specific advice. I wanted to learn how other companies were creating API documentation, how I could be better at communicating with users, examples of bringing the documentation closer to the product, and guidance about collaborative documentation, both internal and external.

Instead, the conference seemed focused on a other things. There was a lot of suggestions about incorporating mobile users, and dire warnings if you didn’t. I don’t disagree, but for the product I was documenting at the time, mobile really wasn’t an option; the doc tool I was using was ok on a mobile device, except that the pesky TOC was difficult to use. So that did help me move to my “Death to TOC sidebars” position.

Similarly, there was a lot of talk about delivering documentation in ePub format, and tool vendors happy to help you do that. But…seriously, ePub? How is that really any better than PDF? It’s delivering manuals instead of real online help, and that would be a step backwards for me. If you’re forced to deliver in that format, you absolutely want to be sure that you’re delivering a quality product. But to me that’s like making sure you give your users the best clay tablets you can possibly create, with absolutely perfect cuneiform and a smooth, well-crafted form factor.

One thing that stuck with me was the growing evangelization that search is key. Users search, they ignore TOCs, and we need to account for that. I’ve LINK written about that before, and my (evolving) thoughts about that are based on conference experiences and arguments in techcomm blogs.

Help for a small team

When I attended LavaCon, I managed a small team of writers. Two, in fact, and that included me. That was two writers to about 45 engineers, 2 PMs, 12 customers support and customer success, and a large professional services team. The total size of the company was around 175 employees.

So I was also looking for advice about managing a small team, collaborating with other teams (getting people outside the doc team to help write content), and tools/processes that were affordable for and could be managed by one or two writers.

Mainly, I found that no one else had any better answers than I did. I think techcomm people are either figuring out what works for them (and not worrying much about what other people are doing), or they’re still working with the tools that they’ve always used, just with fewer people to manage them.

If you need to create manuals, use FrameMaker. If you need to create online help, use RoboHelp or that new upstart, Flare. Then there’s a smaller percentage of writers who use wikis, and fewer still who use non-traditional tools to create knowledge bases. So you could fill a room with people interested in learning more about wikis (or confirming their biases against them), but that might be more difficult for me to explain how and why I use Zendesk, for example.

Ok, enough with the rehashing

I think I’m done with this particular set of random thoughts. I’ll get back to more relevant topics next week. Or maybe just post pictures of the bamboo pergola I’m building in the back yard (pergola, btw, is a very odd word), and whether digging out several cubic yards of useless clay and rocks is a metaphor for technical writing (spoiler: it’s not).


4 thoughts on “What did I expect to get from conferences?

  1. Great post, Neal. I’ve also found that conferences can be hit-or-miss. And lately, it seems, the corporate sponsorship of our conferences make for a tools-centric rather than a solutions-centric approach to the workshops. Although, I’m sure the corporations feel that their tools offer solutions…should you have the money to buy them.

    Still, there are some decent workshops or sessions in conferences that at least make me think. I have hope in the Write the Docs conference. That one is still concerned with “how to help readers” rather than “how to create and maintain your brand.”

    It would be nice to see more sessions about workflows and open source apps. My team uses git and Jenkins to source and generate versioned docs (webhelp and PDF). We can easily generate Kindle, EPUB, and other media types, but there’s no call for it among our readers. They’re more concerned with content accuracy and completeness–another good session for a workshop. And editorial workflows in an Agile environment? I would love to hear how folks are doing this. I’ve been working in Agile shops for eight years now, and I still don’t feel that I have the hang of how to impose our doc work in the developer environment.

    Thanks for posting.

    1. Thanks!

      I like what I’ve read about Write the Docs, and the price is certainly reasonable. But it’s difficult to justify without more information (a schedule would be nice). But based on last year’s schedule, it looks like a great “Let’s Get Sh*t Done!” conference.

      I would be interested in learning how your team uses git and jenkins to create and generate docs. In fact, I’d love to hear from a few doc teams about how they’ve made use of non-documentation tools to create documentation (benefits, costs, what cool tricks and workarounds they’ve built). Not every team uses the big doc tools, and I’d be interested in learning about why and how they have built the processes they use.

      I agree about Agile. I’ve seen more people posting about their experiences, but it’s clear that techcomm hasn’t figured it out yet. And again, I don’t think it has a tool solution, but rather a process solution. Or at least a coping mechanism.

      1. A group of writers talking about git and Jenkins? Now that is a conference I would pay for. If only . . . .

        As for us, we don’t use documentation management or content management systems. We only use source control (git). I have not been overly delighted with CMS or CCMS products that I’ve seen. And the prices for these things are way too much, even if I liked the actual things that they did.

        So for our production, we have a Jenkins server that polls our repo in github. If there’s a change, it does the following:

        – Spins up a virtual machine (we’re a cloud computing company, so we’re eating our own dog food here).
        – The virtual machine goes out gets and copies over the files from github and runs our scripts to generate PDF and webhelp.
        – Once the files are generated, the VM pushes these files to our web github repo and then shuts down.
        – Currently, we manually ssh to push our docs from our staging area to our production site–we’re still working on automating this in Jenkins.

        We are using this process for nightly builds as well as for versioned builds.

      2. That’s an interesting process. How difficult was that to set up?

        Are you using Flare, or a similar tool, to create both help and PDF?

        As a single-person doc, support, and training team, I need to find doc solutions that are inexpensive to purchase, configure, and maintain.

Comments are closed.