Blog Archives

How to be a newbie – getting started in a complex new field

I’m starting out on a new role. Still a technical writer, still at the same company, but on a new product, working with a new group of people and a new set of docs. Here are some of my thoughts on getting started in a complex new field.

I’m reading everything I can about my new field, and watching the videos that’ll help me figure out what it’s about. As a technical writer, I’ll soon be immersed in both the technical and the theoretical side of the field. But before that immersion happens, it’s good to find out how people out there in the world are using the technology. The applications where they’re putting it to use. The functions they expect it to perform.

In my case, the new field is machine learning. That’s a big change from my previous role, documenting maps APIs. I loved working on the maps APIs, and now I’m super excited to learn something new.

Noting the new concepts and terminology

As I read articles and watch videos, I’m making notes of the things that puzzle me or are new to me: concepts, terms, methodologies, technologies. These notes may become part of the docs I write, or they may turn out to be useful only to me. They’re valuable, because I’m currently acting as a first-time reader in the field. Later I’ll forget what I didn’t know. It’ll be harder to put myself in a newbie’s shoes.

For example, watching this video about machine learning, I found I needed a new definition of the term “vector”. The video used the term in a way that was unfamiliar to me. I found some help on Stack Overflow. (It turns out that, in simple terms, a vector in machine learning is a series of values, which you can think of as a row in a table.) I made a note of the term and its meaning, in case I decide to add a glossary in the docs.

Discovering the audience

At this time, I didn’t have a good feel for the intended audience. Perhaps the intended audience for the documentation would already know the term that I hadn’t understood. But it did no harm to make a note. In fact, it helped solidify my own understanding of the term.

While reading, I’m looking to get a feel for the various types of audience in the field. This will help me narrow down the audience for the docs. What types of experts are there out in the world? In the case of machine learning, there’s a diverse audience, all the way from machine learning scientists who design the training/inference models, through data scientists who know all about data and want to try machine learning as a new way of gaining insights from the data, and application programmers who don’t know anything about machine learning and just want to use a specific application of it in their app.

Figuring out the workflow

When I first started learning the field, I didn’t look at my own organisation’s existing docs for this range of products. Instead, I immersed myself in what the world out there is doing. What’s the typical workflow that people are talking about and trying to implement? Later, I’ll look at how our own products fit into that workflow, and how our docs explain the flow.

Remembering that things change fast in technology

If you’re moving to a new project with an existing doc set, take into account that things were probably different when the doc set was created. Perhaps the audience has moved on since the early days in that particular field. Perhaps most of your readers now know more about the topic than they did when the docs were written. This is particularly relevant if the technology was new when the docs were written.

Perhaps the readers are using a different set of terminology now. People may have standardised on terms, while it’s possible the docs have not kept up.

As a new reader of the docs and a new entrant into the field, you’re in the best position to notice this kind of thing.

Something I learned while writing this post: newbie versus nooby

There’s a difference between a nooby and a newbie. I didn’t know that. I thought it was just a spelling difference. In fact, there are three terms: noob (or n00b), nooby, and newbie. A noob is a rather naive, some would say even stupid, person. This term is used particulary in the world of games. Nooby is an adjective referring to the type of (silly/annoying) thing a noob would do. A newbie is someone who is new to the field or area under discussion. It seems you don’t really want to be called a noob, whereas being a newbie is not a bad thing. At least newbies can spell!

Advertisements

STC Summit 2017 wrapup

This week I attended STC Summit 2017, the annual conference of the Society for Technical Communication. I’ve written summaries of the sessions I attended. This post is a wrapup of the conference as a whole, with links to my session summaries.

A huge thanks to the STC Summit committee, who’ve put together a fantastic conference this year. It’s been a few years since I was last able to attend a Summit (the last time was in 2014) and it was an absolute pleasure to be here again. I’ve met many friends, made new acquaintances, and learned what people are doing in tech comm.

There were approximately 600 attendees at STC Summit this year. The venue was the Gaylord National Resort in National Harbor, MD, close to Washington, DC. The conference theme was:

Gain the Edge to Get Results

Session summaries

There were approximately 85 sessions, with 5 to 8 sessions running concurrently in each time slot, over the course of 2 and a half days.

I wrote notes on most of the sessions I attended:

Other blogs

Kevin Cuddihy has posted session summaries on the STC Notebook. For example, here’s the post for Tuesday morning, which includes a writeup of my session. Thanks Kevin!

Here’s a good summary of the STC Summit from STC San Diego.

Social event: dine around

On Monday evening we gathered in groups and went to a few of the restaurants in the area. I chose Rosa Mexicana, where the food was good, the decor lovely, and the company outstanding.

The venue and surrounds

For a touch of local colour, take a look at my bookmark’s latest blog post about Georgetown, Washington, DC.

Here’s a view from inside the atrium of the Gaylord National Resort:

A view from the gardens:

The Potomac River at sunset, just a block away from the hotel:

It’s a wrap!

I’ve loved meeting everyone and attending all those interesting, entertaining sessions. Thanks so much to all the organisers, speakers, and attendees!

Publishing in the Cloud with HTML5 at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

David Coules from eGloo Technologies presented a session called “Disrupt Your Ownself: Streamlined Publishing through the Cloud with HTML5”. He described a light publication stream for self-publishing complex technical documents.

Current problems

Even in 2017, we have a number of problems in delivering content. Examples include long-standing print-based workflow, bespoke website development, complex technology, and no easy go-to solution. There are delays in reaching target audiences, loss of control of the versions of content that your audience is using, and authors spending too much time on layout rather than on content.

Technology enablers

David talked about a set of technologies, including HTML5 and CSS3, which turned the web browser into a solid platform for app development. These apps are available on every device that supports a web platform. Such a system can be a single point of delivery for the content developer, while to the user it seems as if the content is available on all platforms.

Web browsers, such as Google Chrome, also offer a number of tools for developers to examine and update their web apps. There are also a number of tools built on top of the browser.

Progressive web apps are apps that run in any web browser, are responsive to fit in any form factor, are available offline when necessary, and feel like an app because they separate content from functionality.

Continuous integration and continuous delivery allow for rapid development and delivery of features.

Developers build apps with the intention of providing integration with other apps, via APIs.

The Cloud provides global scalability, high availability, and integrated connectivity.

Creating content

Assuming your content is published on the web, how do you author the content? David mentioned that you can author content in existing formats, such as DITA or other structured authoring environments, or even Word with templates, and you can build a process for end-to-end automation.

You can package your content and deliver it to your web app in the Cloud. This takes a few seconds. And because your web app is viewable on all devices/platforms, that’s your job done.

An eReader can provide an API, which developers can use to embed the content in their own apps.

David walked through some case studies. One company took only 4 hours to come up to speed with the new publishing process.

Illustrating the use of APIs, David mentioned a case where the company integrated the published content inside a CRM system (SalesForce). Staff could instantly access the published information when on a call to a customer.

A scenario for the future

What about the IoT (Internet of Things)? David mentioned an idea where the technical documentation could pull in information from an IoT machine, about the problem that the machine is experiencing. That information could activate a particular section of the documentation, such as a troubleshooting guide.

Next steps

Hold a conversation about what’s possible. Depending on your environment, this sort of technology may be a long way off or immediately available. Raise awareness at first. Work towards publishing in this way, taking a step towards the potential for innovation that the modern web offers. Think about augmented reality, for example.

Thanks David for a cool intro to modern web technology.

Catering for novices and expert users at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

Laurian Vega presented a session titled “Novices AND Experts, Not Novices OR Expert Users”. I’m very interested in this topic, as it’s a problem that most creators of documentation face: the people coming to your docs may be new to the topic, or seasoned users looking for help with one specific task/concept. How do you optimise the docs UX (user experience) for both types of audience? Laurian’s talk focused on user interfaces. I figure a doc set has its own user interface, and as tech writers we’re responsible for the information architecture of the doc set too.

Laurian is a UX engineer. Her team writes all the words for the user interface (UI) and documentation for around 30 products.

Experts and novice users

Should we have two difference pieces of software to support the two types of users? No, says Lauren.

She showed us Adobe Photoshop as an example of a tool made for experts: graphic designers. But a number of people who are not graphic designers need to use it, and it’s flabbergasting.

People move from being novices to experts. They do this for various reasons, including necessity and initial simplicity of the task. There’s a spectrum of people, from novice to expert. By designing for the extremes, we also cater for the people in the middle.

Novices do well if the UI is simple, and there’s a single, clear call to action. They benefit from tutorials.

Experts know the task they want to complete, and they know how to do it. (Remember, we’re talking about UI here, not the docs.)

Laurian showed the Google search page as a good example of a design that caters for both novices and experts. Note the large expanse of white space, which focuses the user on the main task. The search box is right in the middle, so the eye is drawn to it. There are only two buttons, and you don’t even need to use them. For the expert users, there are extra controls at top and bottom, which you can find if you’re looking for them.

Expert users tend to have extensive domain knowledge. They may not necessarily have knowledge of modern UI design, because they’ve been doing the same task for so long. Expert users tend to take less time to complete a task, and often perform multiple tasks.

If a user doesn’t like your UI, they’re less likely to do well with it. They also don’t tend to spend much time attempting to learn it.

How to design for both experts and novices

Create separate personas to represent novices and experts, and use those personas to step through each task. Aim for 5-7 personas. Laurian walked through some sample personas for novice and expert, using the example of a UI for an online shoe shop. The novice in this case had high domain knowledge, but was a new visitor to the site. The expert had low domain knowledge, but had browsed the shoe shore’s site often.

Make sure you have a persona for the people who hate your UI!

Take a look at usability.gov for useful resources.

Design patterns

Do’s and don’ts in design:

  • Don’t make separate user interfaces. Design the right tool from the beginning.
  • Don’t ask your users if they’re experts. You won’t get a useful answer. Look at your analytics instead.
  • Don’t use different tones for the two types of users.
  • Don’t test with only one segment of your users.
  • Do provide default options, as they help novices as well as experts, particularly for complex features.
  • Provide both a quick and an advanced search.
  • Provide help text and clear feedback. Avoid big blaring red text. Be helpful without being angry.
  • Allow users to skip or dismiss the help features.
  • If you have a lot of jargon in the UI, which assumes domain knowledge, link to a place where that jargon is explained.
  • Provide advanced options as part of the interaction flow. Use progressive disclosure.
  • Add labels to indicate advanced features. Consider hiding the advanced features until the user has gained enough experience to handle them, but make sure users can see those features if they want to.
  • Take care with custom icons. Icons can offer a quick way for users to find what they need, but remember that novices don’t know the icons. Provide tooltips.

Thanks Laurian for your useful insights into designing for a variety of user experience levels and behaviours.

Emotive analytics at stc17

This week I’m attending STC Summit 2017, the annual conference of the Society for Technical Communication. These are my notes from one of the sessions at the conference. All credit goes to the presenter, and any mistakes are mine.

Allie Proff‘s session had the intriguing title of “My Android Dreams of Electric Cats: Are You Capturing Your User’s Emotive Analytics?”

Allie took us through a fast-paced view of analytics and emotions. She started by looking at traditional analytics: bounce rate, time on page, number of views, etc). But this measures the “what”, and not the “why”. The “why” is emotions: how the readers are feeling when they come to the docs.

She talked about emotions, why they’re important, and the science of emotions. She told the story of Phineas Gage, who had a staking pole punched all the way through his brain, and lived to tell the tale. Later studies have shown that when you damage the areas of the brain that connect your emotions to your logic, you can’t make decisions. You can list pros and cons, but not make the decision.

We actually use the emotional part of our brain to make a decision, then use our logic to justify that decision. Emotions engage more of your brain than logic: 7 areas as opposed to 2.

Significance for technical documentation: Story telling engages emotions, which makes it very powerful. User experience focuses on delight. Gamification is a specific example of engaging emotions.

Emotive analytics

Also called emolytics, or emotional analytics: The ability to measure emotions of your reader, for example through their face, voice, wearables, bio-feedback, or text. For example, Facebook infers emotion from people’s updates.

Affective software is software that can analyse a user’s emotions and provide appropriate responses. As a simple example, you might display radio buttons asking how the user is feeling, then provide textual help based on the answers. Allie gave the example of cheery text delivered when the user is filling in a tax return, if the user says they have children.

A more complex example is voice to text software, which can analyse your words and meaning as it processes the input. Beyond Verbal does voice analytics. Their main focus is health care. You talk into the app, and it tells you how you are feeling, based on your tone, with a view to telling whether someone is well or sick.

Also face detection software, which discovers a face in an image. CV Dazzle is a website where you can find out how to trick face detection software. For example, cover up the bridge of your nose between your eyes, and add asymmetrical patterns. Sunglasses dont work. Affectiva provides software (Affdex) that can quantify emotion, such as joy, surprise, anger, based on your face as you watch a video. There are SDKs available for developers to use. A cat scored 99% disdain.

There are a number of companies providing affective software. Allie’s presentation deck lists a number of them.

Allie also showed us some companies producing robots that show or teach emotions to some extent.

Thanks for a fun and informative session, Allie!

%d bloggers like this: