Sarah Maddox's Blog, page 10

2018 conferences now open on Tech Comm on a Map

The Tech Comm on a Map application now caters for 2018 conferences. This week I updated both the web app and the Android app to accept data for 2018. I also archived the 2016 conferences.

Tech Comm on a Map is an interactive map showing items of interest to technical communicators around the world: conferences, groups, businesses, societies, courses, and other things we find interesting. Tech Comm on a Map is available as a web app (see the previous link) and an Android app.

Highlights of the latest update:

I’ve added a  [image error]  option, which you can click to add items to the map (new in the web app only; the Android app already has an Add event option in the menu).
I’ve added a data type for 2018 conferences, and archived the 2016 conferences (web and Android).

[image error]

Each coloured dot on the map represents a conference, business, society, group, course, or something else. Click a dot to see what it’s about.

Adding 2018 conferences and more

The map is now able to accept 2018 conferences, but there’s not much data on the map for 2018 yet. At this point I’ve added just two 2018 conferences. I’ll add more over the next few weeks.

If you have time, please do add items to the map: 2018 conferences, groups, societies, educational courses, and more. It’s also fun to add tidbits that you think are of interest to tech writers and have a geographical relevance. For example, the Other item type includes the birthplace of Ada Lovelace. Try de-selecting all event types except Other, and see what’s there now.

To add an item:

Click the new ⊕ icon [image error]  on the web app.
Or select the Add event option in the menu in the Android app.

If you’d like to know more about the apps, how they work, and where the data comes from, take a look at the page about Tech Comm on a Map.

Doc sprint at Write the Docs day Australia

Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.

Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.

At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:

Dart, led by Sarah Maddox
Kubernetes, led by Jared Bhatti
Cyrus (email), led by Nicola Nye
webpack (JavaScript module bundler), led by Chris
ReactiveUI.net, led by Geoff

What happened in the sprints

[image error]I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:

Angular setup guide
Angular template syntax
Angular architectural overview
Another pull request is in progress, to update the page on the Angular HTTP client

The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!

At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.

Things people learned

[image error]For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.

Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.

For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.

The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.

For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.

It was hard work

It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.

There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.

Swapnil: “Good, OK, I’ll leave you to it.”

Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.”

Technical Communicators Conference 2017 wrapup

This week I attended the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a summary of my impressions of the conference, with links to the posts I’ve written about each session.

I thoroughly enjoyed this conference, with its atmosphere of dedicated professionalism mixed with warm friendliness. The event took place in Sydney, Australia, filling two days with 14 technical sessions. By my rough estimate (I counted the tables at lunch) there were around 60 attendees. Most were from Melbourne and Sydney. A few people flew in from New Zealand, one from the west coast of Australia, and one from the US. Let me know if I’ve missed out any other travellers from far-flung places!

Conversations

As is often the case with conferences, one of the best parts was meeting and talking to people face to face. Many were old friends whom I’ve met at other gatherings over the years. It was also great to make new friends.

A common theme arose in my conversations with the other writers. Those who have a role in a company or organisation find that there’s way to much work for them to handle. Even if they’re lucky enough to work with one or more other writers, there’s still a firehose of work pouring down on them. (This wasn’t so much the case with the writers who run their own businesses.) The people I spoke to said it was a good position to be in, yet at the same time they wished the organisations would allocate more budget and/or make more tech writing positions available. The writers feel strongly that they’re making a large contribution to the customer experience or process efficiency of their organisation, and could improve things even more if there were more writers around.

I think this sentiment is a very positive trend. Tech writers recognise their worth and feel that they’re doing valuable work. There was no frustration in the way people spoke. No-one said that their work went unrecognised within the organisation. They just wished there were more of them around.

The nice thing about a smallish conference is that you meet the same people more than once during the course of the two days, and can build up a relationship with them over that time. Most people attended all the sessions (there was only one track). People exchanged opinions enthusiastically during and after the sessions. During some sessions there were even jokes flying around between presenter and audience members.

Sessions

Here are my posts about the sessions, in reverse chronological order, with the conference’s last session at the top of the list:

Yes but I have my phone by Grant Mackenzie
The vibe of XSL-T by Tony Self
Writing micro-content by Margaret Hassall
Documenting the tools you use by Swapnil Ogale
The wonder of walkthroughs by Sonja McShane
CSS Variables by Dave Gash
Framework for evaluating communication by Neil James
A tech writer, a map, and an app by Sarah Maddox (that’s me)
Customising Microsoft Word by Rhonda Bracey
Collaborating with developers by Dash Gash
Get your words in order by Sonja McShane
Bootstrap by Grant Noble
Structuring content by Margaret Hassall
Ten terms you thought you understood by Tony Self

Thanks

Thank you so much to the ASTC committee and the conference organisers, for all the hard work you’ve put into this conference. It was excellent. Thanks also to the presenters who put so much time and energy into preparing and presenting the talks.

Yes but I have my phone – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Grant Mackenzie presented a session with the enticing title of Yes but I have my phone. I didn’t take any notes during this talk, as the conference organiser asked us to put away all pens and laptops. The point of the session was that you can do everything with a mobile device. I guess I could have taken notes on my phone, but somehow that seems to me like I’m paying less attention to the speaker than when I’m using my laptop. Something to do with the focus of attention and the posture required to take notes on a tiny screen. Entering text on a mobile screen also takes more time than typing, even though I’m an adept swiper. In fact, I’m writing this post on my mobile device, while on the bus on the way home from the conference. So, for me anyway, this is one use case when a laptop, or at least a keyboard, is better than a mobile screen.

Back to Grant’s presentation, which was lively and packed with information. The main thrust of the talk was that you can use a mobile device to create engaging, informative content. In particular, Grant demonstrated the use of various apps to create professional videos and photo-based art, complete with green screen effects and good audio.

Release notes came up again – they’ve been popular in this year’s conference. Grant’s approach is to have two important people in the company talk through the items in the release notes, while illustrating the features on screen, either behind the speakers by use of the green screen, or fullscreen using the speakers’ words as voice over.

We also saw some cat videos.

The vibe of XSL-T at ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Tony Self presented a session called The Vibe of XSL-T. Tony’s plan is to show us where XSL fits in the XML universe, and then where XSL-T fits in and where it’s useful. He demonstrated, by asking the audience, that most of us were using XML to store at least some of our content. Another of Tony’s goals is to discuss the level of expertise we need, to use XSL-T.

What is XML?

XML is a format for storing information.

XML tags are generally semantic, which means a human being can generally understand its purpose by reading it. Unfortunately, some designers of XML documents don’t necessarily follow that best practice.

Tony edited a .pptx file (a PowerPoint presentation) in a text editor, and demonstrated that you can change the content of a presentation by editing the XML as a text format. Understanding that Office documents are essentially XML underneath gives you some power.

The help format known as .chm is also an XML-based format. Internet Explorer, which has been able to render XML for years, can therefore render the content.

XML is a common way of storing information. A useful ramification is that you can write reports based on the XML.

XML is more like a family of languages rather than a specific language. It’s a set of rules for creating a language. Most XML languages are semantic in nature, in that they define concepts such as dogs, breeds, height, weight, and so on. There are standards for creating XML languages, and strict validation rules to enforce them. The rules are stored in a DTD (document type definition) or an XSD (schema definition). XML is Internet-friendly. The XSD, XSL, and XML files can all be stored in different location.

The rules and standard patterns mean that all tools that understand XML can also understand all forms of XML. For example, editors, browsers, VCRs.

What is XSL?

There are a few types of XSL:

XSL-T: transforms a document from one format to another, where the format is some form of text-based content. XSL-T  determines how the data is arranged, which data is omitted, and so on.
XSL-FO: transforms a document to some type of page-oriented medium, such as PDF. For example, you can convert a file to Apache-FOP and then PDF, using a process controlled by Ant.
XPath: finds information in an XML document. You use it to navigate through elements and attributes in an XML document, and retrieve the part of the document that matches your search criteria.

More about XML

XML is beautifully organised, making it simple to use. Most of the XML standards are still in version 1, a testament to the care taken with the original design.

Tony walked us through some examples of XML, and of using XSL-T to transform a document into an HTML page.

Thank you Tony for a good overview of XML technology.

Writing micro-content – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Margaret Hassall presented a session entitled Writing micro-content, or Writing content for people in a hurry. She talked about headings, Twitter, and content.

We need to figure out whether people are reading our content, and how much of it they’re reading. Take into account the fact that people scan content. Margaret touched on Nielson’s research on eye tracking, showing the areas of a page on which people spend most time.

Even given the new technology like Twitter and mobile phones, the basic principles of content creation haven’t changed. Be concise, and consider your audience. People just want to get in, get the information, and get out. Push for plain language and fewer words. Add headings, shorten your sentences, add pictures. Most importantly, figure out your audience and write for them. Consider why they need the release information.

Margaret’s pet peeve is release notes. When reading release notes, readers want to know what’s changed and how the change affects them. Many release notes are full of content and make the relevant information hard to find. Margaret walked us through some examples of release notes, pointing out good and bad aspects of each, from a technical communication point of view. Comments that came up:

The order of the issues listed in the release notes. Should the items be in order of the issue number, the description, other…?
Grouping of issues by category.
Clear indication of whether the item is about a feature or a bug fix.
Inclusion of a bug number for reference.
Link back to the issue tracker.
Changing of the description, so that it no longer matches the original issue description. This can cause a problem for customers who can’t match the fix against the reported problem.

Margaret discussed the possibility of including tech writers in issue management. We could, for example, write better titles or better descriptions. Sometimes the title of the bug describes the problem as understood by the user, but when the issue is fixed, we find that the title no longer adequately describes the problem.

It all boils down to considering your audience and why they need the release information, then presenting the information to them in a clear, concise document.

Margaret also touched on headings in a document, and on subject lines in email messages.

Thanks to Margaret for these interesting insights into release notes and other documents that people are likely to read in a hurry.

Documenting the tools you use – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Swapnil Ogale presented a session titled How do you document the tools you use? His presentation was about being a technical writer on a product that you also use.

A quick look at some tools with good docs

These are the tools Swapnil uses regularly, for both business and personal use:

Snagit
Meetup
Slack
Confluence
Pocketbook (an expense budgeting tool)

All the above products provide a decent set of documentation and tutorials. Swapnil gave us a quick overview of the help/documentation systems provided by each tool. In some cases, he said, the documentation was easier to use than the actual product.

Introducing rounded (a software application)

Swapnil also uses a software application called rounded, and has contributed to the documentation for the application. Rounded is an accounting tool designed and built by Australian freelancers and sole traders.

When Swapnil started using rounded, he found that there was no documentation, and some of the UI was a little confusing. So he got in touch with the company and offered his help. They hadn’t considered the need for documentation up to that point.

Experiencing rounded as a customer

Swapnil talked about his initial experiences as a product user:

He didn’t know what to expect from the product. Up to that point, he’d been using a collection of spreadsheets for accounting. He was looking for something to make things easier.
It wasn’t clear why he should use the product.
He needed an overview of features that would help make his freelancing life easier. Timetracking was the number one feature he was looking for. Another was reporting.
He wanted to know if the product supported automation, such as breaking his work into smaller elements of time.

Luckily, rounded did cover all his needs. He had some questions though, and he thought it was likely other users had the same questions. Hence his offer to create the docs.

Documenting rounded

The client brief that rounded gave to Swapnil was:

Create content that describes how to use the product, is simple to read and understand, and makes it easy for new users to learn the product.

They needed something that was a simple as spoken language, rather than technical.

Swapnil created an information plan (just one or two pages describing expectations and deliverables). He created a design prototype in the form of a wireframe, using a tool called Pencil.

The early workflow: To draft the documentation, he used Gitbook. When the client was satisfied with the drafted content, they copied it and pasted it into WordPress, and used WordPress as their publishing platform.

The current workflow: Swapnil uses Google Docs to draft content, which makes commenting and reviews easy. Then the client copies the content and publishes it to Intercom.

The ongoing story of the docs

When Swapnil first created the docs, he documented his own workflow and use case. Then he needed to think about how other customers were using the product and what their needs were. To find the answers, he looked at some customer feedback. Some of the feedback was useful, but some of it was way off topic. Next, he talked to the analytics team. They had useful data on the way recent changes in the UI had changed customers’ approach to the product.

The customer requested a change in voice and tone of the content. They wanted a more conversational language, and Swapnil did his best to satisfy that requirement.

Another request from rounded was to add the “so what” factor. The docs should help customers understand why they should do something. For example, why would you want to create an invoice. Look at real customer examples to provide relevant content. Swapnil recommends that you tell a story when creating the docs.

Thank you Swapnil for an interesting look at a tech writer’s experiences as both a customer and a documenter.

The wonder of walkthroughs – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Sonja McShane presented a session called The wonder of walkthroughs. This was her second talk at the conference. Nice work Sonja!

The problem that led Sonja to use walkthroughs was a very confusing experience that her company’s website presented to customers. Sonja demonstrated a tool called WalkMe. According to Walkme’s marketing content, the tool helps you to “foster optimal customer journeys, reduce needed support and ensure user adoption with intelligent guidance”. [Sarah’s note: It looks like a tool that helps you build a guided help experience on your application or website.] In Sonja’s session we saw a “quick tour”, a “help centre”, and a “show me how” walkthrough. In the “show me how”, for example, the user can click a button and follow the guided tour to complete fields on the form.

Using WalkMe, you can add tooltips, validate field values, and lead a user through a process. There are a number of other options too, including surveys, live chat, search, and more.

What about single sourcing? A walkthrough solution kind of does it for you. Because each piece of information is linked to the UI, this means that you don’t have to repeat the same information for each separate use case. The help content for the shared functionality uses the same tooltip or help item.

How do you choose which parts of the website need a walkthrough? Sonja’s team looks at user feedback, customer surveys, and other channels. WalkMe provides analytics and insights that help you see how your customers are using the site and the obstacles they encounter. You can use the output of the analytics to decide which walkthroughs to create next.

There are other tools available that offer similar functionality to that offered by WalkMe. [Sarah’s note: Try searching the web for “guided help tools” or “walkme alternatives”.]

Thank you Sonja for an introduction to a useful tool.

CSS Variables – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

He’s back! Dave Gash’s second session of the conference was CSS Variables: No, really! Dave said using CSS variables is easy. Let’s see whether he convinces me.

In the early history of CSS variables, there were some changes in implementation. The changes resulted in improvements, but not all browsers supported every version. Browser support for CSS variables has improved over the last year. It’s reached around 70-80% according to caniuse.com.

Why use variables in CSS? The benefits are the same as in other types of coding:

Ease of maintenance
Simplicity
Consistency

Declaring a CSS variable is the same as declaring any CSS selector, except that you need to add a double dash in front of the variable name. Examples:

--bqindents: 40px;

--warningtextsize: 125%;

It’s good practice to declare all your variables at the top of your page, using a :root selector. The :root selector gives the variables global scope. Use it like this:

:root {

--bqindents: 40px;

--warningtextsize: 125%;

}

To use the variable later in the CSS, you use the var function to retrieve the value of the variable. Example:

p.warning {

color:red;

font-size: var(--warningtextsize);

}

Dave ran through a number of best practices for using variables, and pre-emptively answered some FAQs. Then he walked us through some examples of where variables are useful. You can find some demos of CSS variables on Dave’s website. Dave has also written an article about them on Medium.

Thanks Dave, that was informative and fun. And yes, it does look kinda easy, now that you’ve shown it to us.

Framework for evaluating communication – ASTC 2017

I’m attending the Technical Communicators Conference 2017, the annual conference of the Australian Society for Technical Communication (ASTC). This post is a live blog of a session at the conference. In other words, I’m writing as the presenter speaks. Any mistakes are mine, and all credit goes to the presenter.

Neil James presented a session titled Will it work? A new integrated framework for evaluating communication. Neil is the executive director of the Plain English Foundation.

The first question that Neil addressed was, “Why do people write ‘Manglish’, or mangled English?” This topic wasn’t a prepared part of his presentation. Instead, it was something the conference organiser asked Neil to consider, following on from a session yesterday. Here are some of the contributing factors that Neil mentioned:

At school, we imbibe the notion that complex writing is better writing. Waffle gets reasonable marks, provided it’s elegant waffle.
Early in our careers in the professional and technical workplace, mastering and using the technical jargon of our field gives us a stronger feeling of belonging.
When we learn the tech vocabulary of a particular industry, it’s difficult to adjust to communicating with a lay audience.
Institutional culture reinforces the language patterns. Large organisations move slowly. It’s hard to change their processes. When you do successfully introduce change, the organisation moves steadily along the new path.
Language is used as an expression of power. Sometimes, people deliberately use jargon to protect their financial interests or to manipulate public opinion. An example is from the airline industry, when people use the term “loss of separation” of two planes, which means the two planes collided.

Evaluating technical communication: Testing versus techniques

Neil talked about the various ways of evaluating technical documentation. There tend to be two groups of people: those who focus on user testing, and those who focus on techniques such as readability formulas.

Communication professionals tend to evaluate their work using a technique they learned near the beginning of their careers, and to use a fairly narrow range of techniques. Neil advocates making wider use of the spectrum of methods available.

Neil’s talk covered:

The evaluation methods available
Criteria for selecting the right method
Examples

The spectrum of evaluation methods

One of the key things that’s happening to our role is that we need to produce a wider variety of technical communication. Neil says we also need to consider a wider range of evaluation methods and tools.

The methods for evaluating tech communication tend to focus on the following three areas, which Neil talked through in detail:

Focus on text – tool based or expert review
Focus on users – preference testing or performance testing
Focus on outcomes – transactions (such as errors, phone calls, revenue) or attitudes and behaviours

Note that you can blend and scale these techniques to suit your environment and requirements. The various methods are not as difficult as we sometimes think they are, and learning about them adds to our professional expertise.

Criteria for selecting the right method

Many of the criteria are familiar to communication professionals. The value of the framework is that it brings these criteria together in a structured way.

Here’s a summary of the factors that affect your choice of method:

Requirements related to the reader:

Number of readers, literacy skills, knowledge of content.
Complexity of the content and of the task.
Urgency of the task.


Requirements of the business:

Timing (standard to disruptive).
Costs.
Risks.


Outcomes shared by both: Purpose and impact of the communication. Sometimes the purpose of the communication may be perceived differently by the organisation and the reader. Similarly for the impact.

Putting it all together

Neil showed us a tabular representation of the above items, which you can use to decide which types of evaluation to use. He then ran through some examples showing where and how he’d used the framework to decide which types of evaluation would be useful for some specific use cases.

The framework is still in its early days. Neil and his colleague, Susan Kleimann, are still testing the framework and getting feedback on it from customers. One point he emphasised is that the framework helps to secure budget for the evaluation part of a project. Once you put the framework in front of customers, they can see the need for the evaluation phase.

To get a more visual idea of the framework, take a look at an early version of the slides from a conference in Dublin in 2015. Neil confirmed that the information on those slides is essentially the same as presented today.

Thanks Neil for introducing a useful framework.