Category Archives: Write the Docs
The next Write the Docs meetup in Sydney is just around the corner:
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.
We’ve just announced the next Write the Docs meetup in Sydney:
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.
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!
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:
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.