Blog Archives

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.

Peter Morville at STC Summit keynote

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:

My presentation: Open source and Season of Docs

Season of Docs presentation at STC Summit

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.



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.


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 and 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:


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.

How analytics can change your world, 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.

Analytics! They’re all the rage, and something I’m very interested in. David Payne presented a session called Analytics Can Change Your World. The subtitle of the talk was Or Justify Your Existence.

David’s goal in this presentation is to help us find the data that will help us prove our worth within an organisation. He said that the tool you use is not important. It’s what you do with it that matters.

The story of a team’s journey into analytics

David told the story of his team, which started from a small size with little clout. The team also had no insight into how their content was used or how often downloads occurred. They didn’t know who used the docs.

They started by collecting data using surveys. They had no way of finding out where users started from. The survey consisted of 20 questions. They had 300 responses over 3 years. The results were largely that the docs were “the worst ever seen”, “horrible”, and so on. There was no actionable feedback.

Next they added feedback links to the doc pages. Received thousands of responses. Not one of them was about the docs themselves.

The team also now knows how many people download the docs. The number has increased from 4 downloads in 2013 to more than 60,000 in 2017.

What to do if no-one is reading the online help?

At first, page views for the online help were very low.

  • Advertise – for example, add a banner on the printed docs.
  • Encourage add a hook in the product itself (Clippy?) to encourage people to view the online help.
  • Engage – talk to customers about how people use the online help.

David showed how the page views for the online help increased year by year.

Using your metrics

When you have the data, you need to start asking questions. David walked through these:

  • Which OS and browser are they using? David mentioned that his business stakeholders wanted this metric, even though to him it’s not relevant. Lesson: Have the pieces of data you want, but be ready to answer all sorts of questions.
  • Did the searches yield the results that the user wanted? For example, some information is legitimately not in your help because it’s relevant to other organisations, but people still search for it. In David’s example, over 60% of search results were not the ones the customer wanted. Tactic: David ran focus groups with customers. Many of the customers said that they turned off the online help for their users. The reason was that the product was very configurable, and thus the screenshots and information in the help were for the baseline system, which was not useful in a highly configured system.
  • How many page views per product? This result was not very useful, as it showed nearly 50% under the category “other” – these relate to search results and the home page, rather than single pages. This result did show, however, that there were 2000 topics in the docs. That’s too many for people to navigate around. David’s team is now working on reducing the number of topics and on improving context sensitivity.
  • How effective is context sensitivity? See how often people are arriving on the first page of the help as opposed to specific pages.

Next steps

Some strategies are to examine the data:

  • Focus on improving the high-traffic pages. Create a home page that highlights the most popular topics, so people can find them easily.
  • Find data for pages that have no views. Find out why people aren’t going there. If the page is important, raise its visibility. If the content is irrelevant, consider removing it entirely. David’s team managed to cut 400 out of 2300 topics.
  • Examine the search queries. For example, the number one search query was “transcript”. Discuss this with the product team and ask why people can’t find the transcript. Make the application so user friendly that the docs are not necessary.

Market the data throughout the company. Product managers may be able to glean the features that need more support. Development and QA can see which areas of the product the customers find tricky. Customer support may be able to use your data to support their own findings.

David discussed a few more questions we can ask about the data. He remarked that there’s no such thing as too much data.

In conclusion

Thanks David for a great overview of the type of analytics we can gather and how we can use the data.

Mentoring and being mentored, 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.

As a senior technical writer, mentoring and being mentored are much on my mind. Carrie Sheaffer and Eva Miranda presented a session titled, Be the Best You Can Be: Mentoring and Being Mentored.

As an introduction, Eva talked about her positive experiences with her mentor at uni, and how she strives for a growth mindset. Carrie talked about the moment when she realised that she was now a senior tech writer, and thus the one people looked to for advice. It was scary and wonderful and empowering.

Eva and Carrie met through STC, then started work at the same organisation, and kind of fell into an informal mentoring relationship. Instead of an informal mentorship, they recommend a more formal approach in which you define and measure your goals.

There are many types of mentorship, including:

  • Peer to peer
  • Speed
  • Traditional
  • Group
  • Network
  • And more

Perhaps you’re already mentoring someone…

… but don’t know it. If you’re helping a junior team member and advocating for them, then you’re already mentoring them.

You can be a mentor without being a manager. The mentor gives advice, whereas the manager gives rules.  Mentors are interested in your growth, while managers are responsible for your performance.

Defining your goals as mentee and mentor

A mentee (person being mentored) has certain goals, such as job satisfaction, opportunities to look out for, career advice and leadership opportunities.

The mentor also needs to know what they will get out of the relationship, even if it’s a little less tangible. Examples of their goals are to get a skilled team member and increase the performance of the team. Many mentors also gain satisfaction from giving back and sharing skills.

At the start of the mentoring relationship, the mentor and mentee should sit down and establish their goals. They should also review their goals and the achievement of the goals at regular intervals. The relationship should be reciprocal.

The mentoring relationship

Another good idea is to get to know each other. See if there are any shared interests, hobbies, or activities.

Be positive and open, and be sure to praise effort as well as skill. Make connections at the workplace, hold regular one on ones, and work together on the relationship.

Schedule fun outings, and aim for levity.


Carrie promised that feedback doesn’t need to be scary (even though it actually is!).

Some tips:

  • Distinguish between something that is a personal style preference versus a rule. For example, the mentor may have a preference, or the rule may come from a style guide. The mentee can choose to follow the former, but has no choice about the latter.
  • Talk about a piece of writing, rather than just asking them to rewrite it. Sometimes the talking through the topic is so much better than what was written, and the mentor doesn’t need to do any more.
  • Make suggestions, like “what do you think about trying…”
  • If you see a repeated pattern, don’t comment on every single occurrence. Just mention it once or twice, and say there are more occurrences.

Remember that the goal is for the mentee to grow, not to show what’s wrong. The mentee is thankful when the mentor takes time to explain the reason for feedback on a doc, rather than just enter the correction.

A tip for the mentee: Don’t freak out!

Feedback should go in both directions. The mentee should review the mentor’s work as well as vice versa. The mentee has something to contribute, and the mentor makes mistakes. The mentee can ask something like, “I noticed you did this, can you explain why?”

The mentee can learn as much from giving feedback as well as from receiving it.

When there are disagreements

What do you do when you have disagreements about the way to do something, and you can’t resolve the disagreement?

Get other opinions. Remember there are different viable ways of doing things. Make the discussions constructive, and don’t become emotionally invested in a solution.

Remember: The goal is to improve.  When you have a product that is better, everyone wins.

The mentor must own their growth

The mentor can’t tell the mentee how to grow. The mentee defines their goals and the direction they want to go in. Then they identify the help they need, and discuss that with the mentor.

Ask for help when you get stuck. (Eva and Carrie showed us a haiku that they wrote to illustrate this section. It was fun.) Especially if there’s a deadline, ask for help directly.

If you’re working on something in a certain direction, and you think there’s a better way to do it, speak up.

The problems

There can be problems in a mentoring relationship. Mentoring is hard, and it’s no fun if the relationship is not working. Maybe you just don’t get along, or maybe the mentor is just not good at mentoring or good at their job. Perhaps the mentee is not progressing.

There are some options:

  • When you’re reviewing your goals, suggest a change or suggest ending the mentorship.
  • Suggest that the mentor moves to a different role.

When the mentee advances to a new level

On the positive side, any perceived problems in the mentoring relationship could be because the mentee has advanced so far that they no longer need the same level of mentorship. An approach is to address this when reviewing your shared goals. Perhaps the mentor needs to change their mentoring methods and the mentee needs to change their goals.

The mentor can start giving the mentee more advanced projects, and reducing the amount of detailed, low-level feedback.

In conclusion

Thank you Eva and Carrie for a lively and thoughtful look and the mentoring relationship.

%d bloggers like this: