Blog Archives

Two Australian tech writing conferences just around the corner

Are you in or near Australia in October and November? Then you’re in for a treat. We have two technical writing conferences in a row, within a stone’s throw of each other. Well, for some definition of “stone’s throw”, anyway. 😉

First up is the annual conference of the Australian Society for Technical Communication, which takes place in Surfers Paradise on 12-13 October. The conference theme is Let’s get technical, technical. Learn about CSS smart selectors, rethinking DITA, speeding up your web pages, blockchain, impossible docs, becoming an efficient writer, Simplified Technical English, and more. Follow up with a focused workshop on web coding. Check the list of presentations and fill in the registration form.

Next up is the Write the Docs AU conference in Melbourne on 15-16 November. This is the second WtD AU conference ever, following on from last year’s debut. This event offers a mix of presentations, lightning talks, workshops, and unconference sessions. Check out the schedule and get a ticket.

Found on a walk in the bush – patterns on the bottom of a squashed mushroom. Intriguing:

Doc fixits and content strategy at Write the Docs Sydney on Tuesday

The next Write the Docs meetup in Sydney is just around the corner:

Sydney: Content strategy and doc fixits

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

28 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba **Five steps to successful content strategy** In her talk, Michalina will share examples and practical tips …

Check out this Meetup →

What’s happening

We have two presentations lined up, preceded by pizza and chatting!

  • Michalina will talk about five steps to successful content strategy.
  • I’ll follow with a presentation on doc fixits: What is a doc fixit (hint: a way of fixing doc bugs en masse), why would you want one, and what can you do with it once you have it?

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.45pm.

At the Atlassian offices, 341 George St, Sydney.

Would you like to join us?

If you’re interested in technical documentation, you’re welcome! Sign up at the meetup and we’ll see you there.

Next Sydney Write the Docs meetup at Atlassian, July 3rd

We’ve just announced the next Write the Docs meetup in Sydney:

Sydney: Content strategy and more

Tuesday, Jul 3, 2018, 6:00 PM

Atlassian
341 George St, Sydney NSW 2000 Sydney, AU

3 Documentarians Attending

Join us to chat about docs – why they’re a Good Thing and how to make them even better. Tech writers, engineers, editors, product managers, more – if you’re interested in docs, you’re welcome. —————— Presenter 1: Michalina Ziemba Five steps to successful content strategy —————— More details and more presentations in the work…

Check out this Meetup →

What happens at the meetup

We currently have one speaker, Michalina, who will talk about five steps to successful content strategy.

There’ll be more speakers, and the opportunity to chat to old and new friends.

Who can attend?

If you’re interested in technical documentation, you’re welcome!

Date, time, and location

Tuesday 3 July 2018, at 6pm. We aim to finish around 7.30pm.

At the Atlassian offices, 341 George St, Sydney.

Want to air your ideas?

If you have an idea for a presentation or a lightning talk, let me know.

Thoughts on a remote Write the Docs meetup

On Wednesday this week, the Write the Docs (WtD) Australia group held a meetup entirely in cyberspace. Or, in the cloud, remote, virtual… whatever you’d like to call it. 🙂 Here are some thoughts on the experience.

Huge kudos to Swapnil Ogale for thinking up the idea of holding a remote meetup, organising it, and running it. It was a great idea and worked very well.

To attend the meetup, we all logged in to a GoToMeeting session. The meetup consisted of a few lightning talks and a couple of presentations. You can see the lineup in the meetup details.

The biggest takeaway for me is this:

People really do want to share their thoughts and experiences with others.

The lightning talks were a great way of doing that. Some presenters had slides, others just spoke from the heart. The variety of topics was intriguing, and listening to the talks was rewarding.

The chat screen was alive and humming throughout the meetup, with people commenting on the topic that the presenter was currently discussing, and on related topics, and on completely unrelated matters too. It was fun and enlightening to be able to watch the presentation and the chat at the same time. This is something that an in-person meetup doesn’t offer. During an in-person meetup, people sit quietly during the presentation, for the most part, and discussion happens afterwards.

It was good not to have to travel. I enjoyed the luxury of going straight home from work, powering up the computer, attending the meetup, then stepping out of the room to join my husband for dinner.

As with all meetups, whether virtual or in person, it was great to see everyone. Especially the speakers who enabled their video cameras so we could see their faces while they spoke.

The remote meetup was also a slightly scary experience, especially for me as a presenter.

I’ve jotted down some notes of what I found scary (I scare easily), primarily so people know they should persevere if they run into technical glitches when connecting to a remote meetup or presenting at one. Things usually work out!

We didn’t know which online platform we’d use until a until a few minutes before the meetup: candidates included Google Hangouts, YouTube streaming, or GoToMeeting. We eventually went with GoToMeeting, which worked well once it was working. I was on a Linux laptop, and the GoToMeeting compatibility checker told me I’d be unable to install the software (eek, but I’m presenting a talk!) but then it mentioned I could use the web interface. Why not just tell me all will be OK and leave it at that? Then GoToMeeting demanded a password, which I did not have. Swapnil was on that immediately, and sent a message to the group saying we should just enter a single space, which worked.

The next hiccup was audio. I couldn’t get mine working with the meetup platform on my laptop, so I dialled in on my mobile phone. All good, but five minutes later the meetup platform managed to find the audio on my laptop after all. Major audio feedback. So I had to decide whether to trust the software and kill the phone call, or mute the software and go ahead with the phone. I killed the phone call, which turned out OK, Luckily so, because by this time it was my turn to give my lightning talk.

When you’re presenting to a remote audience, it’s like talking into the void, You have no idea if people are still there. And I couldn’t get my speaker notes to play well with the meetup platform, so I had to speak without them. That went OK too!

Phew, presentation finished. It was very nice to hear people come back on the audio connection, and nice seeing the comments in the chat room about my talk.

My final thought is:

What a great community we have. Let’s do it again!

Doc sprint at Write the Docs day Australia

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
  • webpack (JavaScript module bundler), led by Chris
  • ReactiveUI.net, led by Geoff

What happened in the sprints

I ran the sprint on the Dart docs. Dart is a programming language with accompanying libraries. Developers use Dart to create apps that run in a web browser (Dart code compiles to JavaScript), servers and command-line applications, and mobile apps via the Flutter SDK.

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:

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!

%d bloggers like this: