If you look at the surveys and other data collected about tool usage and priorities in the technical communication field, it's impossible not to acknowledge FrameMaker as one of the most common tools. Year after year it appears at the top of the charts, and print publishing remains a high priority. Although commonly known for its print publishing capabilities, FrameMaker also has an excellent responsive HTML5 web output. Getting responsive design right is difficult, particularly with documentation websites that have robust navigation sidebars. FrameMaker's responsive output is both mobile-friendly and impressively designed.
MadCap Central, recently released in early January, is a new cloud-based collaboration and publishing solution for tech docs from MadCap Software. MadCap Central allows you to configure and deploy Flare builds from a central server. You can also manage tasks, teams, users, and other details related to each of your projects in MadCap Central.
With developer documentation roles, some level of coding is required. But you don't need to know as much as developers, and acquiring that deep technical knowledge will usually cost you expertise in other areas.
I'm giving a TC Dojo presentation this Monday morning (Jan 9) on Swagger. If you're interested, you can register and attend for free. The event will also be recorded.
TC Camp is holding its annual free unconference for Tech Comm on Jan. 21 in Santa Clara. TC Camp starts with morning workshops given by experts in the field for a nominal fee. The unconference follows, where attendees vote on the topics to be discussed. It's a great event for networking and exchanging ideas, and I'll definitely be there.
I've been thinking about how I should focus my time with knowledge building in my tech writing career, especially given my context in a large organization. Lately, rather than primarily writing content, I've been playing more of a content curator / tools developer / publisher role. I'm okay with this. But sometimes I feel like I have to choose between acquiring deep technical knowledge versus acquiring deep tech doc tools/publishing knowledge.
Episode 2 in the Write the Docs podcast is now available. The topic of episode 2 is findability: How do you allow your users to find what they're looking for in your documentation? We talk about various tools for findability: search, tags, faceted filters, sidebar navigation, inline links, related links, terms/glossaries, and breadcrumbs. In this post, I also share a few more details about Lunr search.
This past week I made some contributions to the Jekyll documentation, and in making the pull requests, I realized why technical writing is often so difficult. Making a request to one documentation topic often requires you to adjust other topics as well. So often we place the bar for contribution at whether someone can write. In reality, it's not just whether someone can construct clear, grammatically correct sentences. It's whether the person can integrate the information into a larger documentation set.
The Write the Docs community now has a podcast available. The podcast follows a discussion-based format with several co-hosts talking about recent articles or topics related to tech comm. The podcast is available on almost every podcast platform.
Ralph Squillace, a senior content engineer for the Microsoft Azure Infrastructure team based in San Francisco, California, recently gave a presentation to the STC Silicon Valley chapter (on November 14, 2016) on Open Authoring -- Collaboration Across Disciplines. In the presentation, Ralph talks about Microsoft's approach to scaling their authoring and publishing efforts across the company by embracing Markdown, Github, open source tools, and other processes that allowed everyone in the company to write and contribute to Azure's documentation.
Peter Gruenbaum has a new course on Udemy called Coding for Writers. Overall, this course takes a unique angle in not only teaching you the basics of coding (in this case, mostly JavaScript and Java), but also teaching you how to document the code, such as focusing on parameters, responses, and data types. He even talks about style conventions in the documentation, including verb tenses, code formatting, and sentence structures.
Apple's recent dongle fiasco raises an interesting tech comm question: Is there ever a time when you, as a technical writer, should apologize for something product-related in your documentation? I looked at Apple's end-user docs about their ports but didn't see any acknowledgement that they were inconveniencing their users in an extreme way. Instead, the tone was merely straightforward and factual about which adapters you would need. When an issue is controversial or obviously of deep concern to users, documentation should address the issue head-on. You don't need to try to communicate about the issue in an emotional way (though that tone might be welcome to users), you just need to include the information, mostly following Redish's documentation-as-conversation model.
In contrast to other non-IT professions, the rapidly evolving pace of technology means that our experience a decade ago is practically obsolete. With new platforms, programming languages, workplace methodologies, and other changes coming on the tech scene every year, IT professionals must implement an approach of continual learning to survive.
Apple's new Macbook laptops include a Touch Bar that replaces the function keys at the top of the keyboard. You can program these keys with your own custom functions. I was curious to see what the documentation for the Touch Bar looked like. In looking at the Apple docs, the most interesting element is the image sizes -- the original image sizes are 4 times the size of the shown graphic. This technique helps create a sharp, crisp look to text when the large image is constrained to a smaller size in the browser. However, if you're translating your content, text callouts can be problematic.
In the deliberation about authoring formats -- whether to use Markdown or reStructuredText or DITA (or something else) -- one detail that is frequently overlooked is the importance of the accompanying tool or platform that uses that format. You almost never use these authoring formats alone but rather with a tool that stores, processes, and renders the source into an output. The tool you use with the authoring format is almost as important as the authoring format itself.
