Report from first Write the Docs Brisbane meetup

Today I attended the first ever Write the Docs meetup in Brisbane. It’s the third in the super-popular Write the Docs Australia series.

We started by going round the room introducing ourselves and describing the document we’re most proud of. Stories ranged from blogs, books, and job ads, to documents that actually contained the word “blah blah blah” before given tech writer luv.

img_20170202_185511

There were 3 presentations at this bumper session:

  • From Hackathon to Help System, by Jared Morgan
  • No-contact Customers: Customer proxies and how to use them, by Laura Bailey
  • Writing clearly: a super-power for software developers, by Josh Wulf

From Hackathon to Help System

Jared Morgan gave an amusing and information-packed account of how he implemented an open-source help solution for a product that wasn’t originally designed to support embedded help. He talked us through the original idea for an open-source help product, which he worked on with a partner. The system was to be written in AsciiDoc. The plan was to render the help on hover, using asciidoctor.js.

Jared and his partner didn’t get around to implementing that solution, but an opportunity came up to use the idea at Ladbrokes, where Jared currently works. He initiated the project during a hackathon: putting embedded help into an existing system. There were a number of challenges, because the system wasn’t designed with user assistance in mind. For example, there was no easy way to uniquely identify the fields.

Jared introduced us to a new term: DragonForce a solution. The term comes from a heavy metal band that’s enthusiastic but not particularly methodical in approach. The basic idea was to render the help content when the user clicked a help button. They also wanted to use open source technology, and to use single sourcing of the content.

The tools:

Then came the serious task of releasing the product to real customers. Jared told us how the system needed to be refined and go through QA to prepare it for release. And he gave some pointers into things he’d do otherwise on hindsight.

Jared’s take-aways from the project.

  • Developers do care about docs.
  • DevOps teams to get things done, and are worth getting to know.
  • It’s good to get outside your comfort zone, and learn the challenges the developers have.
  • You can think outside the box, and not let your department define the scope of your role as tech writer.

No-contact Customers: Customer proxies and how to use them

Laura Bailey talked about no-contact customers – that is, people you can’t get in touch with. Technical writers need to know their audience. But as businesses grow, customers tend to get further away. So what can you do when you have a no- or low-contact audience? Laura talked about how to be your own data scientist.

img_20170202_185434Customer proxies are people and systems that you can use to represent your audience. These are people or systems who have a closer relationship with your customers than you do.

Examples of people who may be customer proxies are sales staff, consultants, developers, data scientists. On the systems side, there are support requests, comments, forums, site metrics, surveys, and so on. You need to analyse your own organisation to find out which apply. Laura mentioned that you can even search the Internet for complaints and reviews of your product from customers.

Once you have the data, you need to process it to make it useful. Scrub it and structure it. You may need to do this manually, if you’re listening to phone call recordings, for example. Or automate the scrubbing if you can work with log output, for example.

A hint from Laura is to think of the future, when analysing and recording the data. Think about aspects of the data that you may need to use in future, and record the relevant data points now. It’s also worth noting that often you’re working with systems that are designed for teams other than tech writers, such as sales staff. So think carefully about which data points can provide insights into the questions you have.

Scrutinise your data, and bear in mind where it came from. Avoid confirmation bias. Find as many data sources as possible, and try to support your conclusions with data from more than one source.

It’s a lot of work, says Laura. Data and its analysis is one of the biggest problems in the tech industry, and is currently a focus too. So take care to target your workload to the questions you need answered. Use the work to proactively prevent growth of the problems you’ve targeted.

Writing clearly: a super-power for software developers

Josh Wulf gave a rollercoaster talk about his experiences in developing Magikcraft.io, which teaches children to code in Minecraft. My summation: Trillions of GitHub commits, oodles of smart people, crazy love of code.

Josh invited us to observe 10 seconds of silence for all of the unread docs. 🙂 And he played us some Roger Troutman.

Some nuggets from Josh: Sometimes we think that language just describes things, but language actually creates the world. It gives us the ability to observe our own actions. At first you’re unconscious of your actions. But then you write it down, and you can analyse it. Bug reports are a good example. Diagrams do the same thing.

A good way of helping people is to ask them to tell you, and to tell themselves:

  • What I did.
  • What it did.

That’s often enough to solve the problem.

It’s a wrap

Thanks to Swapnil Ogale and all the Write the Docs attendees for another great meetup!

Advertisements

About Sarah Maddox

Technical writer, author and blogger in Sydney

Posted on 3 February 2017, in technical writing, Write the Docs and tagged , , , . Bookmark the permalink. 4 Comments.

  1. Looks like a great talk! Will it be coming to Sydney?

    • Hallo Charlotte, we’re hoping to organise another WtD meetup in Sydney soon. It probably won’t have the same set of talks as the Brisbane session, but maybe we can persuade one of the speakers to make the trip. And I’m sure Sydneysiders have some great ideas for talks too. The first Sydney session was excellent.
      Cheers
      Sarah

  2. Thanks for the report Sarah. Always amazed at how quickly you blog about these events. Thanks for making the trip to Brisbane too!

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: