My Content Strategy Journey
If you’ve started a technical writing department, been a lone writer, migrated content, or simply worked at a variety of companies as a technical writer, you’ve probably seen at least a few of the formats and tools I’ve used in my content strategy journey.
I recently learned that my experience is unique. I went through 3 acquisitions and was solely responsible for managing content for at least another 3 companies. I feel like I’ve seen it all (I’m quite sure I haven’t)! But, I’d love to share what I have seen with you. Here’s a roadmap of my journey, the places I worked, the tools I used, and the deliverables. Each number is a different job, but the iterations are migrations of content, either as a result of an acquisition or an internal directive.
1. Advanced Docbook XML
I started my career developing content in Docbook XML and publishing it in HTML help (sometimes called “chum” after the .chm extension of the HTML help file) for an enterprise software company. We also published hard copy books, PDFs, and CD-ROMs from the same XML files. This approach of writing once and publishing multiple outputs from the same source was revolutionary at the time. And it still is.
We wrote topic-based help from the user action point of view. We acted as UX consultants (we were the only ones in the company advocating for users) and wrote “context-sensitive help” that displayed when you pressed F1 with your cursor in a field.
If you don’t know what I mean by F1, you were probably born after 1995. F1 is the first in a series of function keys (“F” for function) on a keyboard, to the right of the esc key in the upper left corner, above the number row. If you needed help in a GUI software program, you pressed F1 and a new window opened with HTML help. This was cutting edge in the late 90s and early 2000s.
2. Manuals and the Pitfalls of Large Doc Sets
Two years later, I was in Silicon Valley writing documentation for network routers. Help displayed in the command line interface and we wrote manuals in unstructured Framemaker. I had gone back in time.
I was perplexed. This was Silicon Valley! Aren’t they supposed to be cutting edge? Didn’t they know that manuals were old news? And, worse, the manuals were structured like this:
- Large title
- Overview text about the chapter (I weep inside just a little even thinking about chapters, but I digress)
- Bullet point table of contents of the subsections
- Subtitle
- Overview text about the subsection
- Bullet point table of contents of the sub-subsections
- Sub-subtitle
- Overview text about the sub-subsection
- Actual useful content
- Summary of the sub-subsection
- Summary of the subsection
- Summary of the chapter
- Repeat
Finally, they switched to a Docbook implementation that was supposed to resemble DITA, but it was heavily restrictive (think unordered lists can only come after a paragraph, but ordered lists must come after 2 paragraphs). This frustrated writers. Eventually, we migrated to the new parent company implementation of Docbook. Much better, but MS file folders were the storage system, which was not great for reusing content.
3. DITA, CCMS, and Source Control
At my third company, I wrote content in Word then implemented DITA and tried to implement Vasont. Lesson learned: DITA is good, but you don’t need a CCMS to manage content. SVN (which integrates with Oxygen) works great for 95% or more cases. The last 5% is a chance to be creative.
Also, don’t implement a CCMS on a closed network (i.e., not connected to the Internet) without a network admin and at least one technical person to help implement. I failed in trying to do all this and write at the same time.
4. Wordpress to DITA to Markdown
At the next company, I wrote and managed content in Wordpress, then AEM (after the company was acquired by Adobe), and then converted the content to DITA. After at least four content migrations from one tool or format to another, I thought I’d seen it all.
Until I learned about Markdown.
Markdown is clean and simple. It’s easy to use and create professional published output. You can implement and use Markdown with free and open source tools. Developers can contribute easily. You can structure your repository to enable easy translation to reduce localization costs. And you can still write user-focused topics for reuse. After migrating to Markdown at Adobe, I was sold.
5. Implementing Markdown
My most recent foray into creating process and infrastructure for B2B software used Markdown with Github, rendered through Jenkins to build a website using Gatsby. I had tech support to implement all this, and I structured the information to support multiple releases. It was a blast. But, we did lose some semantic reusability without DITA. Although, at Lavacon this year, I saw a presentation by the Syncrosoft team where you can use DITA with Markdown. Seems promising!
The Trends
Going forward, I see the technical writing tools market shifting even more.
First, UX writing is an important part of technical writing and content strategy. You can get about 70% of the way to helping users (my opinion) simply by building good UX and content into the product. Then, you can deal with edge cases in product documentation.
Second, product documentation is moving towards support help articles more than large documentation sets. Manuals are dead. PDFs are mostly gone. Even doc websites are not that useful unless they are structured like a help center that focuses on user questions and needs.
Third, there will always be a need for content on highly complex topics like APIs, hardware, and network administration. But, this is becoming the exception, rather than the rule. Markdown and Swagger (and similar) are easy for developers to use with no writer at all (which most companies will, at least, try before hiring a writer), so I see these being used a lot going forward. DITA can work for some technical writing applications and it’s certainly useful, but gone are the days of comprehensive product documentation and deep semantic tagging.
So many changes in my 15 years. And many more to come, I’m sure. It’s been a crazy ride. What have you seen on your content strategy journey?
