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.

[image error]

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:

Asciidoctor for source content
Middleman as static site builder
Franklin as static site framework
GitLab for on premises hosting

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.

[image error]Customer 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.