Yesterday was the very first full-day event held by Write the Docs Australia. In the morning we hosted a writing sprint, featuring five open source projects. The afternoon was devoted to five presentations. Of course, coffee and conversation happened throughout the day.
Although short, the writing sprint was fun and productive. Participants learned about open source, fixed doc bugs, discussed information architecture, and got to know some style guides.
At the start of the day, we invited people to pitch for their projects. Then each of the pitchers chose a table in the room. The other attendees decided which sprint to take part in, and joined the relevant table. These were the five sprints:
- Dart, led by Sarah Maddox
- Kubernetes, led by Jared Bhatti
- Cyrus (email), led by Nicola Nye
- ReactiveUI.net, led by Geoff
What happened in the sprints
We had four contributors taking part in the Dart sprint. Our focus was to update selected pages to match the Google style guide. We produced the following pull requests:
- Angular setup guide
- Angular template syntax
- Angular architectural overview
- Another pull request is in progress, to update the page on the Angular HTTP client
The Kubernetes sprint closed a number of issues, pretty much all those that had been allocated to the sprint!
At one of the tables, people spent much of their time discussing information architecture and doc design, using the open source project as the basis for the discussion. The project leader collected two pages of useful feedback as a result.
Things people learned
For many participants, the sprints were their first venture into the world of open source. A participant asked me, “So, after today, can I continue contributing to the docs? How would I do it?” She was pleased to hear that she could continue participating, and she’d do it in the same way as during the sprint. Our table also discussed contributing to open source projects in general: read the contributors’ guide for each project, be aware that pull requests do require work from the repository owners.
Participants needed a basic knowledge of Markdown. I gave a quick overview of the syntax, to get them started.
For the Dart sprint in particular, it was useful to learn a bit about the language. The sprinters’ guide included a quick introduction, and we ran a sample in Dartpad, to watch the code in action.
The open source projects we focused on are hosted on GitHub. Participants learned the GitHub workflow: how to edit files in a GitHub repo, submit a pull request (PR), receive feedback on the PR, make changes to the files in the PR, and re-submit the PR.
For the Dart sprint, our task was to update pages to follow the Google Developer Documentation Style Guide. One contributor was delighted to note that the style guide agrees with her tech writer intuition, overall. Another contributor reviewed a very long page, checking the style guide when in doubt. She found that, in most cases, the page did follow the style guidelines. I suggested that she add this information in the comment when she sent her pull request, as it would be useful information for the repo owners.
It was hard work
It’s hard work editing pages to follow a style guide. The Dart table stood out as being the quiet, focused area of the room. We were all deeply in the zone.
There came a touch of humour to dilute the hard work: a comment from one of the sprinters to Swapnil Ogale, Write the Docs organiser, after he’d been chatting with our table for a while.
Swapnil: “Good, OK, I’ll leave you to it.”
Sprinter, with a smile: “Yes, leave me alone. I’ve got a lot of work to do.” 🙂
Difficulties people encountered
People had trouble with the GitHub workflow at the start of the sprint. For example, when a sprinter first tried to enter a comment on an issue, an email verification request popped up. The experience was confusing.
Some people found it difficult to concentrate in the noisy environment of a sprint, and they felt stressed that they wouldn’t have time to achieve anything in the short time frame of the half-day sprint.
Three hours is a very short time for a doc sprint, particularly when the sprinters are new to the environment and the docs.
Feedback and thanks
If you were at the Write the Docs day, I’d love your comments and feedback on the writing sprints. I’m sure readers of this blog would be interested to know what you learned from the sprints. The owners of the open source repositories would like to know how they can make it easier for people to contribute to the doc sets.
A big thank you to everyone who took part in the writing day and contributed to the docs!
We held the second Write the Docs meetup in Sydney on 2 March. The presentations were on moving into API technical writing, and the story of the Corilla documentation platform.
There was a good crowd at this meetup – around 20 technical writers descended on the Campaign Monitor offices in central Sydney. We were treated to a breath-taking 360-degree panorama of Sydney from the 38th floor of the building, and a couple of entertaining, informative, very different talks.
The recording of the session includes both talks, and is available on YouTube:
Presentation 1: Transitioning into API Tech Writing
The first presentation was from Priya Varghese, a technical writer at Google. Her talk was titled Transitioning into API Tech Writing. A year ago, Priya started work at Google as an API technical writer. Before that, she had many years’ experience as a tech writer for other audiences in the medical, security and education industries.
Priya talked about the questions she had before embarking on this new role, such as: How different is it from tech writing for other audiences? Do I know enough to explain APIs to developers? What if I don’t know how to code? Can API tech writing be fun? Her presentation gives an overview of APIs and the developer audience, the role of an API tech writer, the things you need to know, and the skills you need to acquire. One thing Priya strongly recommends is a mentor, and she finishes her talk by wondering if we should develop mentorship programs to guide and instruct technical writers.
Presentation 2: The Corilla Story
David Ryan, co-founder of Corilla, told the story of the development of Corilla and the forming of a startup. Corilla is an online documentation platform for technical writers, providing documentation authoring, publication and version-control tools. David’s talk was fun and educational, with intriguing glimpses of the roller-coaster ride of a startup founder.
David described how he and his team had the original idea for a new tool while working with a set of tools that was bloated, clumsy, and not designed for technical writing. Their new tool quickly became popular at Red Hat, where David was working at the time. With Red Hat’s blessing, he and his colleague branched out to form their own startup. And the rest is history. Two years later, Corilla is an alumni of the NUMA accelerator in Paris and has customers in more than 80 countries. Watch the video to hear David talk about the journey from then to now.
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!
Yesterday I attended a Write the Docs meetup where Andrew Etter spoke about his recently published book, Modern Technical Writing: An Introduction to Software Documentation.
I haven’t read Andrew’s book yet, so I appreciated this introduction from the author. One thing that strikes me is how interwoven are two aspects of technical writing: firstly, the processes (the way we glean our material and our efficiency and efficacy in writing content); secondly, the tools we use. Every now and then, I’ve heard people say we shouldn’t focus so much on the tools when discussing our profession and how best to perform our role. I’ve thought that too, at times. But it seems to me that these two aspects of our work are becoming more and more interdependent. The tools make a specific way of working possible, and the way we think of our work determines the tools we choose.
From what Andrew said about his book yesterday, the content of the book seems to agree with my above musings. Now, I should go and read that book. 🙂
Modern Technical Writing, the book
Andrew pointed out that you can read his book in about 45 minutes, and that he’s been allotted an hour for this talk! This comment raised a good laugh.
The book is about 11,000 words. Andrew summed it up (with a smile) in about 12 words, which roughly correspond to the highlighted words in the list below:
- Learn – learn your subject matter and get to know your audience.
- Write in lightweight markup – it’s the easiest way to get from a pleasant writing experience to a useful website. Markdown is a good solution, because people want to use it. You’ll therefore have plenty of people willing to contribute to your docs.
- Treat the docs as code – version control and continuous updates. The stability of the docs over time depends on the quality of your updates.
- Create static websites.
The book, Modern Technical Writing, started as a wiki page. Andrew needed information about technical writing to pass on to others. He did a bit of research, to see if anything already existed that he could use. Having found nothing that fit the bill, he decided “I’m the writer”, and wrote it himself.
What makes a book sell?
Andrew spoke amusingly about an FAQ on the Kindle Direct Publishing site: “Why am I not selling? I am a good writer.” The fundamental question is, how do you get people to buy something you’re selling? Andrew said with a smile that he has no idea! He doesn’t do much marketing or promotion via social media. Here’s his recommendation:
If you have something you feel strongly about, something you’ve shown to your friends and got good feedback on, something you think adds value to the world, then put it out there.
The publishing process
Andrew chose Kindle Direct Publishing as the mechanism for publishing and earning royalties. The rules around pricing are really complicated. The magic happens when you upload your book to Amazon, and they transform it to a Kindle book. Amazon is the market leader in online publication, and your book benefits from this.
One drawback is that you cannot test your book before publication. You just upload it, view the highly inaccurate preview, and then publish it.
Andrew showed us a screenshot of his book on Amazon right next to Strunk and White’s Elements of Style. To be near Elements of Style is mind-boggling. But it lasted a very short time. He dispelled any myths that self-publishing is lucrative. He has, however, received very nice messages from people all over the world.
Charging a price for the book
If you give something away for free, there’s the perception that it’s not really valuable. If you give it a price, people are more likely to see it as worth something.
For his book, Andrew thinks that the price of around $4 is in the right range.
What technical writers do
What is the “differentiated value add” of a technical writer? That is, what do we do that no-one else does?
- Consistency – specifically, consistency in tooling. Without tech writers, each engineering team would pick their own tools, which would result in chaos.
- Accountability – someone has to be responsible for creating good documentation. Andrew remarked with a smile that you have to be able to fire someone if the documentation is bad.
- Creation and curation – writers review and take care of others’ content as well as writing it.
- Culture – having good writers around makes everyone else aware of what good writing looks like.
- Good documentation leads to efficiency improvements in many ways. It helps the organisation and customers save time, and time is a precious resource.
Andrew talked a bit about the writing process, project prioritisation, and the team. He joked at the beginning of the presentation that these topics may form part of the second edition of the book, if he ever considers writing one.
The old way versus the new way of producing documentation
Andrew talked about old methodologies and tools versus the new ones, and walked through some code samples. I didn’t make notes of this part of the talk. The details are in Andrew’s book.
Thanks to Andrew Etter for an engaging presentation and congrats on your successful book!
This week we hosted the first ever Write the Docs meetup in Sydney. It was great to see so many familiar faces and to meet so many new people too.
The Sydney meetup
We had 22 attendees at the inaugural Sydney meetup. The venue was the Google offices in Pyrmont.
Swapnil was an excellent host. Between the two presentations (see below) he asked attendees to introduce themselves and say what they liked most about technical documentation or being a technical writer.
What attendees like about technical documentation / technical writing:
- I like to explain things.
- The scope of technical documentation extends all the way from consumers to developers.
- I like editing a doc when someone complains about it – that means they need it.
- I like to help things go smoothly.
- I’m married to a technical writer.
- Technical documentation says exactly what it means. It cuts out all the fluff, even when describing an error in the product.
- I get to do problem solving in a creative environment.
- I like the ability to make the documentation a tool that someone can use rather than just read.
- Technical documentation captures stuff before it’s lost.
- I truly enjoy the research that goes in before writing the docs. Discovering bugs!
Presentation: Integrating more closely with software product teams
Craig Simms, from Campaign Monitor, presented a talk on how technical writers can integrate more closely with software teams. Campaign Monitor works off an agile development process. As processes change, the technical writing team must change to keep up.
Craig’s presentation was amusing and engaging. He told the story of how technical writing started at Campaign Monitor as a community building role, but it quickly became apparent that it was a core technical writing role. Quite quickly, the two writers in the company felt that their role description and placement in the company didn’t reflect the value that technical writers bring to an organisation. They decided they needed to join a product team.
Craig described the two years of adventure he and his co-writer have had, attempting to get into a product team. They’ve not yet succeeded, Craig said with a laugh, but he gave a zestful account of the lessons learned, and the steps they’ve taken towards that goal. One of the questions that’s arisen is this: Is product the right place for technical writers? An attractive alternative is to be part of the marketing team.
This quotation from Craig’s presentation in particular rang true with me:
Define your own value, and never stop telling people.
Here’s the recording of Craig’s presentation:
Presentation: Wrapup of Write the Docs Prague
Swapnil Ogale presented his summary and take-aways from the recent Write the Docs Prague conference.
Swapnil talked about these topics:
- Why he attended the Prague conference.
- Attendee demographics – he showed a lovely picture of the venue and participants.
- Range of topics covered – wide, including fiction and health!
- A deep dive into 2 presentations he found most useful.
- The unconference part of the event – spontaneous sessions on what people wanted to talk about.
- Key takeaways from the conference.
An interesting statistic:
70% of participants are working on dev docs, APIs and UI text.
Here’s the recording of Swapnil’s presentation:
Where next for Write the Docs Australia?
I’ve been lucky enough to attend both meetings of the Write the Docs Australia group. Perhaps I can keep a good thing going and join the third, wherever it may be. Brisbane, anyone? 🙂