Blog Archives
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!
Report from Write the Docs Sydney, March meetup
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.
Designing tutorials – some insights for API documentation
I’ve just published a blog post on the Google Geo Developers Blog, about a new design for the Google Maps API tutorials. I’d love some feedback from technical writers. If you have a few minutes, would you head on over there and let us know what you think?
What does Stack Overflow’s new documentation feature mean for tech writing?
Stack Overflow has recently announced the public beta release of its new documentation feature. That is, Stack Overflow now provides a platform for crowd-sourced documentation relating to any number of products, for the people, by the people.
For those of us managing the docs for widely-used products in particular, this means our customers may soon have access to an alternative, crowd-sourced documentation set.
What an awesome experiment for us as technical writers to follow! We’ll be able to see at first hand what our customers know they need, in terms of information about our products. Because this is Stack Overflow, the documented products are likely to be APIs, SDKs, and other developer-focused tools and technologies.
What if the documentation on Stack Overflow turns out to be voluminous and extremely useful – where would that leave us as technical writers working on proprietary doc sets? I think it will give us the opportunity to streamline our content, focusing even more than we do now on ensuring our information is up to date, and that our information architecture is the best we can make it.
In other words, we can ensure our target audiences can find what they need, even when they don’t know yet what that is.
Technical writing is hard. Information architecture is hard. The Q&A side of Stack Overflow works extremely well, because it focuses on short snippets of content that answer a particular question. It’s going to be very interesting indeed to see how well the new documentation feature works, with the more narrative demands of technical documentation.
An issue I foresee is that people will be tempted to kick off a topic, and then tire half way through and end up providing a link to the official documentation. Is that a bad thing? Tech writing know-how says our readers find it disconcerting to have to click around to find their information. It’s OK in a Q&A format, but not so good in a tutorial or step-by-step guide.
I really like Stack Overflow’s focus on sample-driven documentation!
I’d love to hear your thoughts on this development. Where do you think it’ll go within the next few months, and how about within the next two years? Will it fizzle into nothingness, or explode into something huge and beautiful? Will the original Q&A form of Stack Overflow merge into the new documentation form, becoming something new?
Write the Docs NA 2016 wrapup
This week I attended Write the Docs NA 2016, which wrapped up a couple of hours ago. This post is a summary of impressions, with links to my notes on some of the sessions I attended.
One thing that strikes me about Write the Docs is that I’ve spent much of my time talking to people. This is partly because half of each day is devoted to unconference sessions as well as formal presentations. In the unconference sessions there’s a facilitator rather than a speaker, so everyone can contribute to the discussion. Another reason I’ve done so much talking to people is that there are so many interesting, friendly, enthusiastic people to talk to.
There were approximately 400 attendees. They’re people who love documentation – that is, people who know its value. Based on a show of hands at the introductory session, approximately 60% of the attendees are technical writers and about 15% are software developers. Others are UX specialists, support engineers, librarians, knowledge management specialists and more.
Another thing that strikes me is that the pre-conference activity was a half-day hike through the forested hills around Portland. Now, that’s my kind of activity.
The sessions
These are the notes I took from some of the sessions I attended:
- Interactive document environments
- A readable README file
- API documentation tools
- Values of effective tech writing teams
- Internal docs for startups
- From tech writing to information experience team
For recordings of most of the talks, take a look at the Write the Docs 2016 YouTube channel. Here’s State of the Docs by Eric Holscher:
Doc sprints and API doc meetup
On the first day of Write the Docs, we gathered at Centrl Office to write docs and talk about API documentation. It was great chatting to so many enthusiastic, knowledgable writers. People got together and contributed to open source documentation with Mozilla, Google, and more. We filled three rooms to the brim. This photo shows the scene early in the day, before most people had arrived.
Conference venue
Days two and three were at the Crystal Ballroom. What a lovely venue! Here’s the view from the stage looking out across the conference attendees.
A closer view of the murals:
A chandelier:
More about Portland
My travelling bookmark, Mark Wordsworm, has some pictures and words about the city: Lost in Portland, Oregon.
Thanks
A huge thank you to the organisers of Write the Docs NA 2016. This is my first experience of a Write the Docs conference. I’ve wanted to attend for a couple of years, but it’s a long way from Sydney, Australia, to any of the conference venues. This year, everything came together and here I am. It was a great experience, and well worth the trip. Thanks!
ffeathers 