We asked:
Does anyone have any techcomm timesaver tips they’d like to share?
This is what you told us…
Transcript
Hello and welcome to the latest episode of The Cherryleaf Podcast.
In this episode, we’re going to look at technical writing time saving techniques.
Technical writing is more than just writing. A Technical Author or what’s called a Technical Writer in the States gets involved in researching and planning before they start to write. And after they’ve written the content, they have to edit it and they have to publish it. So, in reality, only about 50% of the time of a technical communicator is spent writing.
Having said that, if you could save maybe 20% of your time, then that could free up perhaps half a day a week to do other things, or to create more content.
And this has come up out really by some of the projects that we’ve been involved with recently, and I’ll talk about a couple of those later.
But sometimes when you’re a Technical Author, you have to do a lot of writing and it can be repetitive. It can be that there are a number of README files or changelogs that need to be updated. And if you’re writing your content and publishing it via GitHub, you can also need to create lots of pull requests to submit your changes, so they can get approved and then that they can get published.
In this episode, what we’re going to do is look at three common areas that Technical Authors get involved with, and different ways in which time can be saved. And those are the writing activity, the editing activity, and publishing.
In thinking about this episode and what advice we could give, what we decided to do was to post a question to social media, places like Twitter and LinkedIn, to see if other people had recommendations of time saver tips that they’d be willing to share.
So let’s look at the first section. Let’s look at writing.
It may surprise you that the speed at which most people type is very slow. Certainly compared to how fast we speak.
We speak at about 160 to 200 words per minute. When it comes to typing the average is about 40 words per minute. And even professional typists, people have been on training courses, their speeds maybe 60-80 words per minute. That type of speed. It’s not hugely fast.
And our first ever episode on The Cherryleaf Podcast looked into one approach for writing more quickly, and that was to use machine stenography: where the professionals get up to 200 -225 words per minute. In fact, the world record is 360 words per minute.
So if you’re interested in that approach, I’m not going to cover that on this episode. Have a listen back at our first ever episode, Episode One, and you’ll find out more about that.
That wasn’t an approach that others recommended on social media. There were two main suggestions that people had.
Eric Bergman was one of the people that recommended one of those approaches.
He’s a Process Specialist at Primozone Production. And he said,
Knowing a scripting language of any kind can do wonders in tech comm. Some of the things I’ve created to minimize repetitive tasks are:
– A VBA script that converts Excel data into hundreds of decals for our hardware.
Mike Mee, who is currently on contract as a Technical Author Iron Mountain, he concurred. He said,
I love my Word & Excel VBA for this very reason.
I must admit I’ve not seen many Technical Authors, apart from Mike, who have been developing VBA scripts.
I think if you like scripting, if you like programming in any form, then that’s an approach that would suit you, but not everybody is that way inclined.
The other common suggestion that we had, for ways in which Technical Authors write more quickly was to use text expanders.
And one of the people replied was Mattias Sander, and he on I think it was on LinkedIn said,
Text expansion tools are great 🙂
And he said:
I have built a set of templates that I use for everything from writing emails, and creating project plans to code and text snippets I use for writing.
And he recommended one tool, the tool that he uses, which is called Phrase Expander.
So I had a look at this and some of the other tools that are around in this particular area.
So Phrase Expander is for Windows. It’s $179. And what it says it does is that you can store all your terms, common formulas, and templates in a single place and pull them up instantly by typing an abbreviation. So basically you have a shortcut code for a word, a phrase, a sentence, a paragraph. And when you need to use that, you can enter the shortcut and that text appears. That expands from that little abbreviation that you’ve created into the full text.
So this can be useful for situations, for example, if you are making lots of updates via GitHub and you’ve got to do a number of different commits and summarise each commit and describe what you’re doing.
So you’re updating a readme file to include a hyperlink or to fix any typos, and you’re using the same phrase over and over again, you can add that sentence or collection sentences into the text expander, assign a shortcut code to it.
And then when you need to enter it, you can just apply the shortcut code. And that text will expand to what you want. Personally, I use the Mac rather than Windows, so Phrase Expander wouldn’t be one that I could use. So I had a look around at other tools that do the similar thing over text expanders.
There are quite a few. There’s one called Phrase Express for the Mac. There are some where you pay upfront and you buy them like a shrink wrapped piece of software.
And there are others where you pay on a monthly basis. One, for example, Text Expander, you pay $3.33 a month.
And there are also Chrome plugins. There’s one called Blaze. And you pay $3 per month. And then you can, whenever you’re on a website or if you’re using Google Docs and like, you can have those abbreviations and expand text.
In that situation, one of the promises that was mentioned on Text Expander was that this approach, as well as being a way of writing more quickly and reducing the amount of keystrokes that are needed, was also that it could provide the benefit of, for teams, having more consistent, accurate and current information. That you can create a set of abbreviations that is used collectively, that are shared. That you can share text and you can share images. And, obviously, those being in a central repository, those can be updated as and when is needed. So you can have a repository of emails, boilerplate other content, as you type, that can work across multiple platforms.
Again, like VBA scripts, this isn’t something we use at Cherryleaf. And it is interesting. It’s certainly worth considering whether that would save time on writing.
As I mentioned, these tools tend to be chargeable. Within the operating systems like MacOS there are also some built-in text expansion capabilities. And you can assign key combinations that will expand to be text. So that might also be worth investigating.
One consideration with these text expansion tools is, can you remember the shortcut?
So you have to really come up with a method of designing your shortcuts so that they’re memorable, so that you can use them as and when you need.
If you’ve used text expansion applications, let us know. You can contact me on Twitter, @ellispratt or on LinkedIn, or by email. It’s info at Cherryleaf com. I’d be interested to see how widely used text expansion tools are within the technical writing community.
One discussion we had a while back within Cherryleaf was a more hardware-related approach.
One of the companies that provides equipment for people that are doing recordings of videos, be it for e-learning courses or for vlogging, is a company called Elgato.
One of the products that they offer is something called the Stream Deck. And they come in different formats. And this is essentially a collection of buttons. You can get one with six buttons, or I think 12, and I think 24 buttons.
And what you can do is, you can programme these buttons to do different things. It’s primarily designed so that if you’re vlogging and you’ve got two cameras, you can push a button and you have Camera No. 1 that’s presenting. You push a second button and Camera No. 2 is the one that’s presenting. Push a third button and what’s showing to your viewers is the computer screen.
One of the other things that you can do with these stream decks is also assign macros. So one of the suggestions that Elgato has is that you can have these buttons set up. So that if you want to automate tasks you push the button and it will initiate the macro.
You could in theory have that set up as a text expander or a way of automatically sending information from one application to the next. The cheapest Elgato stream deck is about £80 pounds and the most expensive is £250.
So that’s potentially one approach. One of the attractions of the Elgato Stream Deck is you can assign images that appear on the buttons. So you can remember what it is each button does
Before we move on from the writing side of things, I want to mention something that’s often underappreciated.
And that is, and I’m not saying this because part of what Cherryleaf does is providing training courses.
But one of the main tools or techniques or skills that Technical Writers have for writing quickly and efficiently is their training and their experience.
Now a lot of people say they find writing hard. They get writer’s block. They don’t know where to start. They waffle, they repeat.
And typically, that’s not true, that’s not the case, with Technical Authors. The way in which they approach technical writing, by planning out, by having self-contained chunks of information, means that there’s an economy of writing. That it tends to reduce the situations where content has been written that’s just not needed.
It also maximises the chance of content reuse across different documents. And that writing style, that concision, being able to write clearly, being able to write short sentences, is a skill. It means that the information can be written in a clear way and written relatively quickly.
Now there is a downside or counter to that. When it comes to technical writing that, Technical Writers and Technical Authors want the content to be accurate, and they want it to be complete. So often Technical Authors spend time checking that information is complete, is accurate. That they include the steps that happen next after doing the primary step. And so the time that it takes to write content, can appear slow. But that’s just because it needs to be right.
So we’ve talked about writing. Let’s also look at editing. That’s another activity that a lot of Technical Authors get involved with. That’s part of the process of writing content or generating content.
And one other comment that we got back from various people on social media related to a way of doing that editing and fixing process.
Adrian Warman was one of the people that commented and he said
Learn Regular Expressions. Within editing tools, they’re great for finding and replacing. Add in scripting languages like Python or Perl, and RegExps give you immense power for rapid and *consistent* file manipulation and management. A timeless and very portable skill.
So regular expressions are a way, or like a syntax or formula I suppose, for setting up rules for searching for particular words or phrases and then replacing them. And by having sophisticated expressions, you can have some text be replaced and other text not. So you can control that activity And that can save an awful lot of time where otherwise you might have to manually go through and clean up data or edit information.
Now I know people say it should be called Reg ex, but I find that hard to say, so I’m going to quote some other people and say Redgex.
Steve Arrants was somebody else that said something similar.
Learn Regex. It is a tough nut to crack, but knowing Regex has saved me a lot of time and agita. I tried online resources, but a community college short course was best for me.
You may not know it, but some of the help authoring tools support Regex. RoboHelp for one. And the search and replace capabilities within Madcap Flare are pretty sophisticated, as well.
On the same thread, and I’ll probably get this name completely wrong: Zbyszard.
He also said:
On top of regex – XPath for DITA writers. Combining those two is like entering hyperspace.
So XPath is W3C standard. It can traverse through an XML tree structure and use pattern matching to find elements. So you can do search and replace of information.
In tools like OxygenXML, you have features like XPath Builder View. And I’ll quote from the website for Oxygen XML:
This view allows you to edit multiple line complex expressions and assists you with features, such as the content completion assistant, syntax highlighting, automatic validation and documentation of the currently edited item. The executed expressions are stored in a history list and can be reused as necessary.
So let’s look at the third area where we might be able to save time and that’s in publishing
And often this is the area that’s of main focus within technical authoring tools and conversations that Technical Authors have at conferences. Because there’s that need to reuse content to publish content across different versions, in different configurations, and across different media.
And, in fact, we had a client recently, where there’s been a merger of different organisations. And one team is using LaTeX, which is a way of writing content for academic papers. They’re writing their user guides in that particular way, which seems very, very weird, because it’s a difficult tool to master, and it takes a long time if you’re writing in that way. But for them, the reason for doing that was that they need to create personalised manuals for each customer that they have. Each customer gets the unique solution.
And they can use LaTex and create a template, enter into a form different variables or different bits of information. And they’ve built a method by which then the relevant content can be brought into the manual or excluded from the manual. And they can create personalised bespoke manuals for each client.
LaTex is really only designed for publishing PDFs and isn’t probably an approach that most people would want to follow.
But there are other ways to do that type of thing. And in fact if we go back to one of the comments of Matias Sander and him recommending a text expanding tool called Phrase Expander, one of the capabilities that that has is the ability to create powerful templates that adapt as you fill them in.
And one Use Case for that particular tool is for doctors. Where the doctor can slot in different bits of information into this form, and it will generate a letter to a consultant or to a patient using standard text, varying depending on these conditions that are filled in on this form.
So it can act as a document generator, building an entire document.
And there have been also people that have been looking to do similar type of solutions for tools like MadCap Flare. And, for example, there is a company called Illumina that’s used webforms and some rules within SharePoint to enable customers to go to a website, enter information about the way that their machines configured, and what they’ll receive in a couple of minutes later is a personalised manual that’s been generated with all of their configurations.
Now, as it happens, what’s just been launched is a tool to make that process simpler with MadCap Flare. And it’s a tool that’s been developed by Thomas-Bro Rasmussen.
So let me read from Thomas’s website about Flare-it:
Let’s turn something into something else. Let’s push data into Madcap Flare, drop the manual work and do it right.
Imagine this,
You have a lot of data placed outside of Flare. Of course you want it in Flare.
Using standard methods in Flare for import, mapping and adjustment are, however you look at it, takes time. After all, it does involve manual work. Sometimes quite a lot. And next time it still takes time.
We have developed a framework that not only standardizes such import. We actually push all data into Flare. Leaving you to just build output.
But so what? This enables you to do, for example, is create data sheets automatically from data that’s stored in Excel.
And another suggestion that came up also related to spreadsheets. And that was about an article that was published in Wired, which was “spreadsheets are hot and cranking out complex code.”
There are a number of new applications that have been developed, one called spreadsheet.com and another one called rows.com, which are using spreadsheets as like a content repository for different data. And normally, within a spreadsheet, you wouldn’t have images within a cell. But within these types of web-based spreadsheets, you can do that type of thing. And so we may see document builders being created for generating content in those types of new spreadsheets, spreadsheet.com, rows.com.
It will be interesting to see if that does turn out to be the case.
So those were all the suggestions that we came up with and that others came up with.
That really fell into those three categories of writing, editing, and publishing. With writing: using text expanders and other ways of using abbreviations to expand text for phrases and sentences and paragraphs that are used on a regular basis. For the editing environment: using regular expressions and other ways to avoid having to manually edit content when needed. And for publishing: starting to see a trend of using document builders to select different variables and then to generate that content, either from a text expander itself or it’s integrated with other tools like Madcap Flare or even content stored in spreadsheets.
What else have you seen? How else do you save time? Do let us know. You can contact me via the info@cherryleaf.com web email address. Or on the socials, I’m Ellis Pratt. Thank you for listening to this podcast. Until the next time, goodbye.
Leave a Reply