Two big things happened to me last week. I attended a technical communications conference and it was a worthwhile experience. I picked up a lot of good information, and I tried to apply the tips that people gave me in comments to my I don’t get conferences post.
But that’s not all…
I poked a hornet’s nest and was declared DITA Enemy #1. But to be honest, I’m evaluating multiple documentation tools, including DITA editors, as options to replace my current solution. I’m figuring out the benefits and costs involved with my current (and planned) content situation, and determining whether I can make a case that we’ll see a return on investment in a reasonable amount of time.
I learned a lot from that experience. And not just “turn off alerts at night.”
Write the Docs: What I learned about conferences
When I talked about my experience at LavaCon, I made two mistakes: I suggested that it might be best for novice techcomm people, and I brushed off a lot of things as not relevant to me. For the first point, I’ve come to think that LavaCon is just too large and complex to be a good first conference experience. There are just too many panels, in too many tracks, and too many vendors around. A novice conference attendee (as I was) hasn’t learned how to filter and focus on a few important points of interest. Plus, there’s the desire to see *everything*. With that many panels, you can easily double- or triple-book your time, and have no time left for conversations with your peers. And those conversations, as Sarah O’Keefe pointed out, is the main benefit of gathering techcomm people into one place.
Plus plus, the ticket price for a larger conference is much more difficult to justify.
At Write the Docs, there’s a single track that splits into two for the afternoon. Every talk is 20-30 minutes long. We were sitting around tables instead of in rows of chairs, and that made it easier to talk to other people (not just the people sitting to your left and right).
And what I learned about tech communications
From the talks and the side conversations, I learned that many of the people at the conference weren’t technical writers. There were a lot of tech writers, of course, but there were also engineering leads, product managers, program managers, tech support agents, and other people who wanted to learn about technical communication best practices, or just because they were curious about the field.
In the past, I would probably scoff at engineering teams writing documentation. But now API docs are hugely popular, and programmers are coming up with some really clever ways of solving a new (to them) problem. More than a few speakers advocated treating your documentation like code: Check it in, version it, and track the bug reports. And not in a separate content management system, but right alongside the product code.
(I’ve done that before with online help, but not for all of the documentation.)
And they’re doing it in interesting ways: A couple of teams write the content using markdown, use Git to check the docs into GitHub, and then use static site generators to create HTML help. This is great because it brings the documentation team closer to the engineering team (if they’re even separate), and it means that the engineers are reviewing the docs in a system and process that they use every day.
One downside is that this method doesn’t support dynamic content reuse. It’s also limited to using markdown, even that would do most of what I need. But it’s a very interesting solution that I hadn’t thought of before. Some teams use this because of convenience; another team uses it because they found DITA too difficult and constraining, and wanted an easier write-review-publish workflow.
Obviously, that part got my attention.
Would I go back?
Yes, I would. I also want to give a talk, even though I don’t have a topic in mind. But it’s inspiring to watch a bunch of people who are not professional speakers getting up in front of the crowd and telling us what they do and why. People who don’t go from conference to conference giving the same talk, which I find reassuring.
The Write the Docs organizers also set up room for “unconferences,” and I sat in a few of those (and I tried not to talk too much during those, but I wasn’t always successful). It was great to sit down and have a longer discussion about some of the topics. I got to ask more than one question, the circle of expertise expanded as more people joined in (also, the circle of people asking smart questions that I hadn’t thought of.)
What I’m going to pursue
Just to prove that it was valuable, and that I learned something, here are things that I picked up that are of immediate value (Andrew Spittle has an impressively comprehensive set of conference notes, so I won’t attempt that):
- Building communities: Define what we’re offering people; why should they contribute?
- Remove “be” verbs from the docs: I tend to do this already, but now I want to go back and check.
- Documentation + Design = Usability
- Multiple good suggestions for writing API docs, and examples
- We should treat the content like developers treat the code. Which might mean a CMS, or using something like GitHub. I’ve got a lot of suggestions to follow up on.
- “Wabi-sabi” is a good way to describe my approach to creating content (based on the idea that “the perfect is the enemy of the good” and “a good plan today is better than a perfect plan tomorrow”), or what I’ve been calling “doc triage.”
I met with our UI lead today to start a conversation about integrating help content into the application, so I’m making some progress. I’ll be reviewing doc tools and processes for a while, but I’m also going to create a plan for community-building.
Plus, I’ll be busy plotting the downfall of DITA. Wish me luck!