Tutorials versus docs -- why you need both
There's a new tutorials section in the Jekyll docs. I actually added this new section and contributed a couple of tutorials there. I initially did this because I wanted to become more familiar with github workflows with open source projects, but I also just like playing around with Jekyll. In adding tutorials, we decided to distinguish tutorials from docs on the site. This division between tutorials and documentation is an interesting one. Most documentation could benefit from including more tutorials because tutorials help connect the dots in how you use the various doc topics together.
Moved my API doc site into separate repo
I recently moved my API doc course into a separate repo. Previously, I had the material inside my main site in its own collection. But I wanted to completely separate out the site into its own repo, with its own theme and configuration file and other settings. This will allow me to more easily output the content to other formats, such as MOBI and PDF. I'm happy that I did this, as I think it allows users to focus more fully on the content. It also makes it easier for me to generate the content into other outputs.
Simplifying my life and writing
For a while now I've wanted to simplify my life. When I tell this to people, almost everyone can relate. But the move toward simplicity isn't just about removing busy-ness. Simplicity lets you focus on the things you actually want to do, rather than those things you feel obligated to do but have no desire to do. I have a goal to simplify my writing style as well, using tools such as the Hemingway app and basic simplicity principles.
Guest post -- The effects of terminology consistency on the reader's comprehension and attitude
From a cognitive perspective, what do we know about the effects of terminology consistency on how our readers understand and 'like' our documentation? In this guest post, Yves Pierrot explores how the cognitive aspects of memory, reading, text comprehension, and search strategies potentially influence reader comprehension in tech docs. He admits that research in this area is lacking, so he pulls on his own experience and background in psychology as he reflects on principles such as priming, polysemy, and more.
Crowdsourcing docs with docs-as-code tools -- same result as with wikis?
Adding an Edit on GitHub button to my docs didn't have the immediate collaborative result I anticipated. In analyzing why crowdsourcing efforts succeed or fail, I decided to look back at my efforts with wikis some years ago. Docs as code provides new tools for simplifying authoring and publishing, as did wikis at the time. But crowdsourcing writing proves to be tricky no matter what tool you use. Writing doesn't break down into granular chunks that can easily be crowdsourced, so efforts to crowdsource writing will likely be the same. However, docs-as-code tools can empower people to author and publish their own content -- without expensive help authoring tools.
Write the Docs Podcast Episode 4 -- Continuous Integration and Docs as Code
Episode 4 of the Write the Docs podcast is now available. In this episode, we talk about continuous integration strategies for docs (for style, screenshots, and REST calls). We also dive into discussions around docs as code, including how to encourage developer collaboration, how to stay informed about code updates that developers make, and more.
Adobe FrameMaker 2017 -- time, tools, and the tech writer’s focus on content
Adobe FrameMaker has a new release (called Adobe FrameMaker 2017) that has a ton of improvements toward simplicity and usability. Some of the new features include new responsive HTML5 layouts, auto-complete search, more intuitive menus for authors, and more. Tools like FrameMaker that allow you to focus on content (instead of worrying about creating your own search, site design, pdf output, navigation menu, and more) provide a huge win for both technical writers and companies. The company's documentation tends to be what matters most to both users and product owners.
Upcoming 2017 Write the Docs Conference in Portland
This year I'm planning to attend the 2017 Write the Docs conference in Portland. The conference takes place May 14-16 and draws about 400 people who come together for three days 'to explore the art and science of documentation'. I'll be presenting a short talk on doc navigation best practices.
Guest Post -- MadCap Central: A Review for Companies Delivering Technical Communication Services
The following is a guest post from Michał Skowron and Jakub Wiśniewski, two technical writers working for 3di. 3di is a company providing technical authoring, translation and localization services. In this short review, Skowron and Wiśniewski evaluate MadCap Central, a new product from MadCap Software. MadCap Central is a cloud-based platform where you can host your MadCap Flare projects, manage builds, track tasks, manage users and their permissions, and collaborate with others. The article looks at the product from the perspective of a company delivering tech comm services.
How do you learn what you need to learn to be successful as a technical writer?
Keeping pace with new technology and information is a core challenge for tech writers. You can divide the needed knowledge into four areas: product, technology, user, and industry domains. To limit the scope in each domain, filter by the users' tasks. To find time for the learning, implement morning routines for gathering information and log issues for needed documentation. Then as you work on the documentation and find yourself lacking knowledge, jump into online resources to learn what you need.
Guest post: Design choices for organizing API reference content with other documentation
In this guest post, Derric Gilling, CEO at Moesif, explores various design choices for organizing API reference content in relation to the rest of your programming tutorials. He looks at three different strategies: (1) Centralized docs with separate API reference, (2) Centralized docs combined with API reference, and (3) Decentralized docs. The question of how to integrate API documentation into one seamless user experience -- particularly when you have auto-generated outputs of API reference topics from tools such as Swagger -- is a question that many technical writers regularly ask about.
Recording of User-Centered Design Principles for Organizing Documentation
I recently presented to the STC Twin Cities chapter on User-centered Design Principles for Organizing Documentation. When organizing your documentation, such as arranging navigation titles, workflows, or other wayfinding features, you can apply universal design principles to make your content more user centered. Some of these principles include Modularity, Hierarchy, Five hat racks, and Progressive disclosure. These design principles, based on solid user research from design gurus, will help users better find and navigate your help content. You can view the recording and audio from the event here.
Write the Docs Podcast #3 - Trends for 2017
In this episode of the Write the Docs podcast, we discuss top technical writing trends for 2017. Chris Ward discusses how more technical writers are interacting with support groups, and even being embedded within support departments. Jared Morgan discusses how docs are being planned for earlier in development cycles, as more product managers are seeing the value of docs. I talk about how more technical writers are treating documentation as code, and the challenges inherent in developer tools and workflows.
Technical Writing Trends and Predictions for 2017
My 2016 technical writing trends/predictions turned out to be pretty accurate. For 2017 technical writing trends, I'm predicting that more technical writers turn to Github in their documentation workflows. This trend applies mainly to companies where programming technical writers work with engineers to create developer documentation.
Simplified Technical English and HyperSTE
Simplified Technical English (STE) is an approach to writing developed by the aerospace and defense industries to simplify technical documentation. STE consists of a dictionary of about 900 allowed words and a set of 65 writing rules. Together, this controlled language is formalized into a specification called ASD-STE100, which many regulatory industries must follow to ensure clear, consistent content. HyperSTE is a plugin offered by Etteplan to check your content for adherence to the rules and grammar of the ASD-STE100 specification.
subscribe via RSS