Tom Johnson wrote a series about the ‘trends to follow or forget in tech comm’. He’s put a lot of work into pulling it together and I encourage you to check it out. I feel like I could call BINGO! on a lot of these, so decided to write a brief blurb about my experience with each trend. It makes me feel old.

HATs and single-sourcing

Aah the good ol’ days when things were simple. A fit-for-purpose software tool that did what it said on the box. Adobe RoboHelp and Madcap Flare, CHM files. For me, this was tech writing at its best. I was freshly minted from my post-grad course in Tech Comm and was really confident using these tools and exploring what they could do to present content in a way to suit our readers.

Wikis and crowdsourcing

When your company gets an intranet and has the hope that ‘everyone’ will create their own content and publish their internal docs. They’ll own their space and add roadmaps, updates, retros, and meeting outcomes. But it normally falls to the tech writers to help other teams get their content up, apply IA rules, and enforce style rules. Crowdsourcing content is a nice idea but I’ve never seen it work that well.

Faceted filtering

When your product splits into 3 tiers (Lite, Plus and Pro I think they were called) and the feature sets were different for each, and you want to present tailored docs for users based on their tier. Or you have modular products and you want users to be able to see only the content for the modules they have installed. I remember wrestling with this using HATs and funky HTML components. The idea was that users would self-identify and (hopefully) choose the appropriate help docs. Not sure that we ever got it to work.

Screencasting

I used to make video tutorials for new features (2-3 minutes long). Screencasts are deceptively simple - a lot goes into making them. We’d make a storyboard, then the product managers reviewed it before we’d write a script. During planning, we estimated it took one day to create a minute of video. It took a long time to create usable data sets and samples. I’d try to make the desktop product look better than it was by deleting frames with weird flashes and content-paint delays. I still use Camtasia today and the skills I learned during that time were invaluable.

Quick reference guides

Fondly (not fondly) do I recall one such quick reference guide I worked on. We called it a Getting Started Guide (GSG). It was initiated by the Training Team - they needed a nicely formatted, short guide to explain, at a high level, the key features of the software. It was a companion to the training material and handed out at the end of in-person training sessions. It was jointly owned by the CTO and CMO. We had to get hard copy sign-offs from both whenever we updated it for each major release. The GSG grew, page by page, because we kept adding new features and never removed any content. It was printed and translated. Eventually it was retired due to duplication of effort - ultimately we were describing new features three times: in the What’s New (release notes), the docs and the GSG.

WordPress and web CMSs

I started with Sitecore. It was locked down tight with non editable page types and hidden CSS—tough going for a control-freak like me. Hosted by a 3rd party so all changes had to be submitted offsite in change requests. Ugh.

I used WordPress like a boss for several personal blogs…until they switched to Gutenberg then all bets were off. I migrated to an SSG for my personal site, and now work with TYPO3, an open source CMS. I also get to peek inside Sulu and Drupal (other open source CMSs).

DITA

I remember learning DITA back in my post grad Tech Comm course. I even wrote my first open source project before I even knew what open source was. Working with my lecturer, Tony Self. I converted the Mini manual to DITA. I just checked GitHub: 14 stars, and it’s been forked 7 times!! I used OxygenXML to write it. It was fun, I suppose. I never thought DITA would take off, but I understand it is quite popular in the machining and manufacturing industries.

Content strategy

Ever since my first day on the job working as a tech writer, I’ve wondered how my work fit into the bigger picture. Rather than just document features that the developers were building, I was conscious of the importance of a consistent experience for the user whenever they interacted with any text from the company. That was a while ago, and back then there was little wiggle room for a tech writer to step up and outside the remit of their role.

Fast forward to a more progressive company, embedded in the UX Team, I remember being asked (with my fellow writer) to devise the roadmap for our ‘Documentation Strategy’. How foreign and exciting! We got to step outside of the day-to-day work and think about how best to serve our readers. We looked at analytics, audited our content, thought about different delivery channels (text, video, animated gifs!) and even wrote a vision statement! Heady days!

I recall attending a 3-day marketing workshop during which we mapped the customer journey, looking at the touchpoints of anyone interacting with our company and product. It seemed so obvious to me that there should be a consistent “information experience” that isn’t served by siloed departments of sales, marketing, product, training and support.

Scrum

I remember moving from Waterfall to Agile. To be specific, we followed the SAFe methodology (Scaled Agile Framework) which used agile ceremonies, one of which was Scrum. We had daily standups, worked in 3 week sprints followed by a HIP (Hardening, Innovation and Planning sprint). Not so great for docs but we found a kind of hybrid way to work within the bounds of the system. We did user story planning with the rest of the team, but there was always some part of the docs that lagged, and we’d be doing work in the HIP (when you weren’t supposed to). Scrum was a great way to have oversight of what the devs were building, their challenges, and the different responsibilities of a cross-functional team.

Marcom and techcomm

I’m living it right now. I always knew I could write marcomm, and at my current job I get the chance to stretch my wings a bit and do that. My happy place is techcomm and it’s how I’ll always identify. But our houses certainly aren’t that far apart.

Every page is page one

I remember learning about EPPO during my post-grad Tech Comm course all those years ago. Moving from print to online, every page is page one. Landing on a page cold from a search engine result - you need to provide context and visual cues. You need to orient the reader. Give them something to hold on to and a reassuring handhold into your content. You need good IA and clear navigational elements. These principles never get old. I recently co-wrote a book and was surprised and liberated to be able to use words like “earlier in this chapter” (because books are linear!).

API documentation

My weakest point. The closest I’ve come is documenting release notes for a SOAP web services API. I certainly have an understanding of APIs, what they are, what they’re used for. I have documented working with the command line and I’ve edited API docs written by developers. But in terms of best practice for how to approach a suite of docs for APIs, or creating a developer portal, I haven’t experienced that yet. If and when I do need to gain more experience with this, my first stop is going to be Tom Johnson’s course.

Docs as code

Oh, how I remember the many weeks and whiteboard scribblings when my tech writer colleague and I learnt Git. We were using Flare and moving it to GitHub to be inline with the developers workflow for release management. We’d grab any passing developer walking past our cubicle and corral them into explaining the “blessed master”. We’d draw endless clouds and local versions, with London-Tube-like pipes on the whiteboard. We’d learn it, then learn it again. Grasp it, then lose it, then have epiphanies. It took ages. I’m so glad I’m on the other side of that learning journey.

Once we got it, though, docs-as-code worked quite well for us, with integrated test suites and automatic deployment.

GitHub and open-source

Thankfully I learned Git at my previous job before I moved into working remotely in open source. I don’t think I could have grasped this concept on my own.

Open source is my happy place. I’m intrinsically motivated! Who knew?! I started with the inaugural Google Season of Docs and have not looked back. I am involved with the Good Docs Project, the TYPO3 CMS project and am a general proponent for the philosophy. I highly recommend Nadio Eghbal’s book, Working in Public: The Making and Maintenance of Open Source Software.

Remote work

This is me, and most everyone else these days. I was working remotely before the pandemic (“I liked them before they were cool”). You get good at async communication. I do miss people. I wrote about how you can make being remote and async work act in your favor. Hint: you become a friendly elf!

Check out Tom Johnson’s series, Trends to follow or forget in tech comm