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.
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.
- 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.
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!