STC Summit 2019 wrapup

This week I attended the STC Summit 2019, the annual conference of the Society for Technical Communication (STC). Thanks so much to everyone who organised, spoke at, and attended this event. It’s been rewarding and fun!

STC Summit was packed this year. There were more than 750 attendees and more than 100 education sessions over the two days of the conference proper, as well as a number of half- and full-day training sessions during the preceding weekend, and a half-day plenary session to close the conference.

The keynote presenter, Peter Morville, is a well known information architect and author. One of his books is Information Architecture for the World Wide Web, affectionately known as the “polar bear book”. Peter spoke about information design, cultural trauma, decision making, getting things done, and bricks-and-mortar architecture. This wide ranging talk made a fitting start to a conference about technical communication, in itself a varied and wide reaching profession.

Notes from sessions

With more than 100 sessions in just two days, there was no way I could attend all the sessions I wanted. Here are my notes from most of the talks I did attend:

• Website search with Apache Solr, by Scott Prentice
• Compassionate technical writing, by Robert Perry
• Headless CMS, IoT, and You, by Chad Dybdahl
• More than writers, by Alan Porter
• How analytics can change your world, by David Payne
• Mentoring and being mentored, by Carrie Sheaffer and Eva Miranda
• Optimizing your content like an engineer, by Sara Feldman
• The trending value of tech knowledge, by Tom Johnson
• Sketching is like technical communication, by Elizabeth Alley
• Improving docs and measuring quality, by Barbara Giammona

My presentation: Open source and Season of Docs

I presented a session about getting started in open source documentation. The talk also introduced the new Season of Docs program, which provides a framework for technical writers and open source projects to work together on open source documentation.

Photo from a tweet with thanks to @beckatodd.

 

Denver

The conference took place in the lovely city of Denver, Colorado, in the United States. Snow-clad mountains surrounded us. The weather was balmy for most of the conference, with clouds and snow threatening on the last day.

An innovative design for a table, on the 16th Street Mall in Denver. Even when there’s no-one sitting at the bench, it looks like a happy place to be:

Union Station in Denver:

The big bear at the Colorado Conference Center, next door to the venue of STC Summit:

More about Denver

If you’d like to see more pictures and stories about my trip to Denver, take a look at my bookworm’s blog: Bears and banks in downtown Denver.

Thanks

Another big thank you to the STC Summit planning committee for a great conference, as well as to all the presenters and attendees who made this such a great event. It was a privilege and a pleasure to attend.

Website search with Apache Solr, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Scott Prentice‘s session was titled Website Search with Apache Solr. The presentation covered an open source search platform, Apache Solr, introducing its features and showing us how to install the platform.

Solr is a wrapper around the Lucene indexing and search technology. It has a REST API and some native client APIs.

While Apache Solr is a vast and complex system, it’s not to hard to get in and get started.

A quick bit about search in general

Why add a search to your website? Having your own search helps you keep visitors on your site. You can allow people to use Google Search, but having your own means you can curate the search to your own requirements. Having your own search also gives you insights into what people are searching for, and thus into your content.

Types of search:

• Remote search service through a web form or API
• A static JavaScript search, which provides a precompiled static index accessed via JavaScript
• A custom search platform, which is what Solr is.

Installing Solr

You can set up Solr in a standalone mode, or you can use SolrCloud, which is a collection of search engines spread across multiple servers. Scott showed us how to set up the standalone search.

The process is:

• Download and extract the installation file
• Install
• Start the server
• Test the server

Scott walked us through the process in more detail, which involved creating an installation directory and a data directory, editing a config file, and moving some files around.

Then he started the server from the command line (solr start), and accessed the Solr admin page at a localhost:// address in a web browser.

The next steps involved copying the default schema to create a collection (basically, an index), and adding some example docs as data for indexing. The default schema works, but it’s very broad since it’s designed to handle a wide variety of content types.

Scott walked us through the syntax of a Solr query. You’ll use the query syntax when constructing a search and also if you set up a panel of faceted search results for display as a navigation aid. The default response is in JSON format, but you can request XML or CSV instead.

Customising your search

After testing the search, you need to:

• Customise your schema to suit your content and your website’s needs. Your schema defines the fields for the index. Scott showed us how to create a very simple schema, and how to apply it to your Solr installation.
• Generate a JSON or XML feed from your content, based on the schema. There are various web crawlers available to generate the feed, such as Apache Nutch, Heritrix, GNU Wget, and more
• Upload the feed to a Solr collection.
• Develop a search UI, typically in JavaScript. Scott showed us a simple UI that he’d developed using jQuery. Examples of search UI types include a search form with a list of results, highlighting of search terms, faceting, autocomplete, and so on.

Scott mentioned CORS (Cross-Origin Resource Sharing), which you’ll run into when trying to read data from a remote server. The server owner has to enable the reading of content. So you need to enable your Solr server, by adding a config file. Scott recommends this blog post for help with setting up CORS.

Scott also gave us some tips on securing and scaling your Solr server before taking it to production. You can also consider using SolrCloud.

For a server, consider linode.com and websolr.com as affordable options.

In conclusion

Thank you Scott for a useful quick introduction to Apache Solr.

Compassionate technical writing, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Robert Perry’s talk was entitled Technology for Good: Helping Organizations Do (More) Good with Technology. He spoke about how his organization has created solutions to make technology available to non-profit and educational organisations. He also introduced us to the concept of compassionate technical writing.

These are the primary points in Robert’s task

• Embrace Industry 4.0 in your career and writing. (Industry 4.0 is also called Fourth Industrial Revolution, FIR, or Information 4.0.)
• Use technology responsibly and for social change.
• Create content that people can learn from and relate to.

Challenges and opportunities in Industry 4.0

We’re already living the Fourth Industrial Revolution, says Robert. Innovations are transforming the world we know, and changing how we work and play. This is how Robert characterised Industry 4.0:

Connected

During the session, Robert talked us through the first (steam in the 1700s), second (electricity in the 1800s) and third (computing in the 1900s) industrial revolutions. Each of these triggered profound changes in society.

Then he focused on Industry 4.0. It has benefits and disadvantages. It’s disr

Industry 4.0 is moving far faster and is having a wider effect than any of the other three revolutions. It’s affecting almost every country and society. Technologies include biotechnology, robotics, 3D printing, Internet of things, artificial intelligence, virtual and augmented reality.

These technologies are also changing customer expectations. Customers expect more valuable connected experiences, personalised content, and contextualised content. Customers are not afraid to move to a different provide to get those.

Technical writers can help improve the customer experience. New categories of jobs are arising at the same time as others disappear. New opportunities are becoming available.

Customer feedback is becoming crucial, as is creating personalised, contextualised content delivery. There’s lots and lots of data coming in. Data feeds artificial intelligence, which can help make businesses and documentation smarter.

Trends for technical communication:

• Intelligent content
• Automated content generation
• Dynamic delivery of content
• Neural machine translations
• Service-oriented content rather than document-based product manuals
• And more

Robert said that metadata will drive many of the content delivery models. Metadata will become richer and more complex.

Technical writers will become knowledge managers – people who curate information, and enable the delivery of data-based dynamic content.

Technology for good

People must own the shaping of technology. Businesses are at the forefront, so they should also drive the sense of social responsibility. These are some of the things a business can drive:

• Education and training programs for all
• Ensure equal pay for equal work
• Equality for every human being
• Protecting our planet

There are hefty moral implications for these new technologies, for both good and bad. We build the things we admire, so we must make sure we understand the implications of what we build. We need to ensure that the economic benefits are available to all, not just to a small group.

Compassionate technical writing

The doc team at Salesforce (Robert’s employer) has started an initiative to write docs that show awareness of the customer’s situation. So they’ve started telling stories.

They ask themselves whether they write with a real human understanding of what it takes to use the product. Are we inspired and passionate about our work? Do we feel connected with the user?

Remember that readers should experience patience and compassion while they read. They may be in the middle of a frustrating experience.

How to write compassionately?

• Be yourself.
• Tell a story to help people identify with the documentation.
• Take care of your reader.
• Don’t force it on them. Be judicious – some areas of tech writing don’t lend themselves to compassion.
• Anticipate the questions your reader may have, and answer them.
• And more points from Robert.

The primary point is that every document must be technically accurate and excellent.

Robert recommends a book by Ann Handley, “Everybody Writes”.

In conclusion

Thank you Robert for a thoughtful look at technical communication and our changing world.

Headless CMS, IoT, and You, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

This was a talk from Chad Dybdahl from Adobe, with the intriguing title of Off with Their Heads! Headless CMS, IoT, and You.

Some definitions

A headless server is essentially a box. There’s no screen. It just sits there running something.

A Web CMS, like WordPress, is a traditional tool for building a website.

A headless CMS serves as a content repository. There’s no presentation layer. You’re writing content, and the CMS serves as a repository for the content. There’s a REST API that delivers the content. This makes for a very flexible environment. However, you need developers creating a front end to display the content.

A traditional CCMS also does not have a front end for content delivery. No APIs either. The published content is hosted somewhere else, such as in PDF or a website. Authoring is often done via DITA.

A hybrid CMS combines the best of both worlds, said Chad. It provides a content authoring and repository, a web front end, and REST APIs.

Content explosion

Chad talked about the number of devices that people use (average 6 devices) and the number of content sources (average 12 sources).

Content as a service

Content as a service is where you have a hub that delivers content to various channels. It’s an API-first service. Content delivers can choose the content they need and how to deliver it.

What do you need?

• Structured content, such as that provided by DITA, in a well-defined model.
• A CCMs that provides APIs and an API-first experience.

Demo of an Adobe CCMS

Chad demonstrated Adobe Experience Manager as an example of a hybrid CMS. He showed us a very simple web interface that queried the CMS and output content in the form of HTML (rendered for human readability) or JSON (as an interchange format).

IoT (Internet of Things)

In Chad’s house are various IoT devices that receive and output information and enable automation. On a web interface you can see the views of various cameras installed around the house, the output of the motion sensors and thermostat.

We should see all the items in the house as content. How do you tie together all the output from the various items? Chad uses a tool called Node-RED.

Doing the same thing with content

Chad uses Node-RED to tie pieces of content together too. He showed us the Node-RED tool for building a workflow to use the APIs from the Adobe Experience Manager CMS. We saw the resulting web page, built from a few bits of content from the CMS and rendered into HTML.

In Node-RED:

In Adobe CMS:

Rendered as HTML:

In conclusion

Thank you Chad for a good introduction to a CCMS and an intriguing glimpse of the wrld of IoT.

More than writers, at STC Summit

This week I’m attending STC Summit 2019, the annual conference of the Society for Technical Communication (STC). I’m blogging my notes from the sessions that I attend. Thanks and all credit go to the speakers. Any mistakes are my own.

Alan Porter presented a session titled Why Technical Communicators Should Be More Than Writers. The alternative title is Why Technical Writers Shouldn’t Be “Writers!”

Alan started his career as a technical author, writing technical manuals for the Concorde aeroplane (British Airways). He said there are mentions in history of Roman times of people consulting the manuals. Even hieroglyphs and cave art are technical writing. He showed us some examples of writing that are hard to read, and touched on best practices:

• Structured content
• Topic-based authoring
• Simple language
• Consistent terminology
• And more

What is our role?

We may think we’re hired to be technical writers, but actually our job is to communicate complex material in a way that’s as simple as possible.

Alan said this is the main takeaway from this session:

Your customer does not care where your content comes from.

What the customer wants

People want answers to their questions: 70-80% of people come to a website because they have a question. The questions are primarily in 2 groups:

• Discover, learn, and train
• Get answers to product or service questions, fix a problem, and enhance their usage of the product.

Most documentation is feature-focused, whereas people want to know how to do something or what the benefit is to them.

Customer experience and brand experience

Documentation and the product should work together to make a good user experience. Alan showed us an example of a tech guide for a product where cables and ports were colour-coded to ensure easy installation. The manual showed diagrams that corresponded to the physical pieces.

The most important thing for companies to focus on is customer experience.

Technical writers are not just writers. We’re the key differentiators. We drive customer experience because we understand the customers and the market.

Every time a customer interacts with content, that’s a brand experience. Alan showed us a page of diagrams that was obviously an Ikea guide, but did not have the brand name anywhere. We all knew the brand anyway.

Next we looked at a Lego guide, which presented the same experience.

Alan said this is the way we should be thinking: Content should align with the brand and the product. Looking back to cave diagrams and glyphs, Alan said that humans have been communicating in a visual way for a very long time.

However, the diagram must convey the message you want. Alan showed us an engineering diagram that was intended to show the rings on Challenger would crack at a certain temperature. The diagram was dense and full of information, and did not convey the intended message.

Visual thinking

Before creating a diagram, we must understand the data. Then we need to decide how to convey it.

Another important step is abstraction. Alan showed a series of pictures of a face, moving from a photo thru various simplified drawings to an emoticon. Babies will react to a smiley face icon before they react to their mother’s face.

Symbols and icons help people understand something quickly. They become part of the culture. But before using them, make sure the meaning is clear.

• There are standards for symbols and icons. For example, for car maintenance manuals, an automotive committee (I didn’t catch the name) has created a standard set of symbols for use across companies.
• Be aware that certain symbols mean different things in different countries. An example is the thumbs up symbol, which has an unacceptable meaning in some places.

Think about colour. For example, in China white is the colour of funerals and morning. Other cultural aspects include whether people in a photo are wearing shoes or not, or the amount of white space on a page.

Alan mentioned many more cultural and design aspects that you need to be aware of. Visual communication is complex!

Where the content will be used

Consider where people will be viewing your content. For example, if they’ll be outside, it may be hard to read on a computer screen.

More to consider

Alan touched on animation, sound, and video. Video is an enormously popular way to consume content. As the next generation grows up, their primary interaction with content will be through voice.

We also had a quick look at augmented reality (AR) in technical instructions.

Alan’s recommentation

Examine a screenplay or a comic book script, and see how those were translated into visual content.

In conclusion

Thank you Alan for an engaging look at our changing role.