In this podcast, we first explore the flourishing community of technical writers in Poland, discussing why the tech writing scene in Krakow is taking off so quickly and what trends this young tech writing community is embracing. We're joined by special guest Pawel Kowaluk, a Polish tech writer who runs SOAP (a tech comm conference based in Poland). We also talk about automation and robot takeovers of tech writing jobs. How are machine-assisted technologies enhancing or displacing technical writers and their work? Given the increase in automation, is tool expertise becoming more or less essential to thrive as a technical writer?
With four kids and a house full of devices, it can be pretty hard to wrangle devices from kids' hands and shut off Internet time. In the past, I tried putting all the kids' devices onto a guest network and all my devices onto a main network. When I wanted to shut off the kids' access to the Internet, I would log into my router and shut off the guest network. Now I have a new approach that seems to work much better.
In addition to being a technical writer, I also play basketball. I might spend more time playing basketball, in fact, than I do writing on this blog. I never played college ball, but I love playing pickup basketball several times a week at various courts. Now that NBA season recently finished, I figure it may be relevant to expound a bit on a pet theory of mine about how to win at pickup basketball games, and how that same strategy might apply to winning at documentation.
Many tech writers have a heavy disdain for Frequently Asked Questions (FAQs) in documentation. At first this disdain seemed a bit unfounded and elitist to me, but now, after a recent project, I'm starting to understand the reasons for the disdain. All too often the FAQ format is abused by non-writers who want an easy way to write. The list of random questions grows with each incoming question until it's a ridiculous hodgepodge of information thrown together, with no larger story or narrative.
Here's the recording of the presentation I gave at the Write the Docs 2017 Portland conference. The presentation explores best practices for doc navigation, including principles such as hierarchy, modularity, progressive disclosure, entry point, and wayfinding. The presentation is about 20 minutes long, and you can either watch a video or listen to audio. Other WTD presentation recordings are also available.
In episode 6, we explore the role of metadata in documentation and how it can be used to classify topics and assist in the discoverability of information. We’re joined by special guest Eva Jackolis who explains a strategy for metadata used in German mechanical engineering documentation. We also discuss involving tech writers in UX copy and the challenges inherent in influencing UI copy, product naming, and working with UX designers and product teams.
If there's been a theme for the past year in tech comm, it's to treat docs like code. Most people get behind this idea with a great amount of enthusiasm. And yet, in many ways, docs are not entirely like code. You can make processes a lot more complicated if you push the docs-as-code idea to the limits. Docs differ significantly from code when it comes to release frequency, release complexity, review processes, and company support.
How big should your documentation repo be, especially if you have multiple products in your documentation? Although you could put all content into the same repo, it might be easier to have lots of little repos. Jekyll accommodates this architecture quite nicely through gem-based themes.
I recently returned from the 2017 Write the Docs conference in Portland, Oregon. The conference had two days of sessions (Monday and Tuesday), preceded by a day of doc writing sprints and workshops. I also participated in a 5-mile conference hike on Saturday. Although this was the fifth year of the WTD conference (it began in 2013), this was my first time attending. In this post, I'll share my impressions of the conference, contrasting it primarily with other tech comm conferences such as the STC.
Slides for my presentation on doc navigation are available below. I'm giving this presentation at Write the Docs Portland on May 15. The presentation is about 20 minutes long.
Testing your documentation is such an important part of tech writing that I decided to expand the sections on testing docs in my API doc course. I actually grouped these pages into their own section, amplifying the content with more detail and better organization.
In this episode of the Write the Docs podcast, we explore where technical writers belong in an organization. Is tech comm best placed within engineering, marketing, product management, or another group? We also talk about strategies for doc navigation, in particular, the merits of inline links and/or sidebar navigation, using a post from Every Page Is Page One as a starting point. Are hierarchical sidebar menus still useful, or are they a relic of the past? Finally, we provide details about the upcoming Write the Docs conference in Portland, and Chris mentions his new book on responsive design.
I recently created an HTML5 web app called Calm Meditation. If you have a Fire TV, you can check out the app by searching for it in the Amazon Appstore. I'm not really into meditation, but I needed some sample video content to test out a web app framework I'm documenting. The idea I came up with for generic video content involved nature still scenes with some background music. I think it worked out okay, actually. There's a whole genre of these types of apps, apparently.
I recently added a tutorial on converting an HTML site into a Jekyll theme. This tutorial shows how easy it is to make any HTML site Jekyll ready with just a few tags. Creating Jekyll themes is one of the aspects of Jekyll I enjoy the most.
In following instructions to assemble a Tinker Crate project over the weekend, I realized that a list of parts (essential for assembly kits) is similar to a glossary in that it teaches you a new vocabulary. Software projects also involve new vocabulary terms, but software instructions often omit the glossary (or list of parts). However, if you look at the glossary as a dictionary for new vocabulary, its inclusion in software instructions becomes just as essential as a list of parts in an assembly manual.
