Category Archives: technical writing
The Write the Docs AU community is holding a meetup in Sydney on Thursday, 21 February.
If you have a view on technical documentation, you’re invited!
Date and time: Thursday, 21 February 2019, at 6pm – 7:30pm
Location: Google, 48 Pirrama Road, Pyrmont (map)
Sign up on Meetup.com
There’s pizza and the opportunity to chat with friends old and new. Then we’ll move quickly to the exciting lineup of talks:
Building awesome technical writers from open source communities
Speaker: Cameron Shorter
The secrets behind inspiring an open source software community to write awesome docs. A story about how we initially got it wrong before improving. (Spoiler – technical writers play a cornerstone role).
Cameron is a software developer, business analyst, open source community builder, and accidental technical writer.
Tech Writers as Agents of Change in the Digital Age
Speaker: Priya Varghese
As we race through the digital era, swiping away one app after another, there are numerous companies and organizations out there that haven’t yet strapped themselves in properly for the digital transformation roller coaster.
Priya Varghese (a technical writer) talks about how technical communicators can become agents of change (in a disguised double role), with the key skills, advantages and vantage points to successfully help their teams on board the digital transformation journey.
Getting started for developer documentation
A lightning talk.
Deepti Korwar, a technical writer, talks about the necessary skills and available resources for writers considering to move into developer documentation roles.
Lightning talk 2
This five-minute spot is open. Suspense! Someone may stand up and speak impromptu at the event.
See you there!
Google currently has an open role for a technical writer in the Sydney office. See the job posting. Here are a few thoughts, from me as a tech writer at Google in Sydney, on how you can prepare to apply for the role.
A note up front: These hints come from me personally, as a tech writer at Google. I’m not the hiring manager for the open role, and following these hints won’t assure you of a successful application.
The advertised role is for a technical writer in the software engineering area. Let’s dive straight in!
Resume, samples, writing exercises
For a tech writing application, the resume is super important. Treat your resume as the first writing sample you’ll submit to Google. Make sure it’s clear and consistent. For example, it doesn’t matter whether you use US, British, or Australian spelling, provided you stick to your choice throughout the document. The same applies to punctuation of bullet items—just be consistent. Avoid unnecessary capital letters, check your spelling… you know the drill.
If your resume shows the skills and experience that suit the role, Google will ask you to submit some writing samples and complete a set of writing exercises.
For the writing samples, make sure you send in the work that demonstrates sound tech writing principles. If you have any code that you’ve written and that you can link to from your resume (for example, on GitHub), that’d be useful too. Even if the code is something you put together while learning a programming language or experimenting with an API, that’s good.
You may be asked to complete some specific writing exercises. Take your time in completing the writing exercises. Apply your tech writing soft skills as well as standard tech writing principles. A good tip is to sleep on it before you submit the exercises. Come back the next day to take a fresh look at what you’ve written. Focus on the intended audience for each sample. Include comments noting any extra information you’d ask for if you were writing the docs in a real work environment.
Once your first interview has been scheduled, you’ll be able to chat to the Google hiring representatives and they’ll give you plenty of information about the interview process.
Usually there are a number of interviews, some by phone and some in person. You’ll speak to people in different roles, which may include tech writers, engineers, developer advocates, managers, and more.
A good hint for the interviews themselves is to remember you’re a tech writer, with the skills of a tech writer, and those skills are not the same as those of an engineer. Your interviewers may be tech writers, engineers, or managers. So, ask questions during the interview as if you were interviewing an engineer or a product manager. Make it clear to them that that’s what you’re doing.
You can find more tips to help you prepare on the Google Careers site.
It’s a good idea to become familiar with Google developer products, docs and style, to show your interest in the role. Be aware of the Google Developer Docs Style Guide, browse the Google Developer Docs site and the Google Cloud docs.
People often ask about the coding requirements for a tech writing role at Google. It’s a vexed question, and you’ll receive different replies depending on the role. This section of the post takes up a lot of space—arguably too much in proportion to its importance—but I’d like to give the best hints possible.
For this role the expectation is that you can comment on things like consistent and meaningful names for methods and classes, good use of code comments, and other aspects of code readability. In an interview, you should be able to ask the interviewer questions about a piece of code, as you would if you were planning to document it.
The job description mentions a few programming languages. It’s a good idea to focus on one (I’d recommend Python if you don’t already have a favourite) and do some studying in the leadup to the interview process. In fact, when I applied I continued studying throughout the process to keep the concepts and skills in focus. Life is busy, and it’s easy for some things to drop down into the less-easily accessible areas of our brains! This Python course is a good one.
To the best of my knowledge, you shouldn’t have to solve a problem in code during the interview. At most, you may be asked to write pseudo code. I’ve heard various reports about whether you need to do whiteboarding of simple code during an interview. I think it depends on the interviewer. I did have to do some whiteboard coding in one of my interviews, and I totally messed it up because I was extremely nervous. I still got the job. I did much better on the conceptual questions (what is a class, what is inheritance, what does “closure” mean to you, and so on).
For this particular role, we’re looking for someone who’s willing and able to continue learning about software and code. It’s not necessary to have in-depth coding skills. If during an interview you’re asked to do some coding that’s beyond your current skills, fall back to discussing the key technical concepts involved and to interviewing the interviewer about the requirements and goals of the application / system.
My top hints
Be passionate about tech writing. Let the interviewers see that you enjoy the role of tech writer, and be ready to tell them why. If you’re active in the tech writing community, let the interviewers know that. Mention any opportunities you’ve had to mentor other tech writers or students.
Be yourself. 🙂
This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters.
Ben Hall‘s talk was about how important documentation is to open source projects, and the changes communities can make to improve their documentation.
This statement from Ben’s introduction rings true with me:
While many open source projects have amazing code bases, the documentation is letting them down and as a result they are losing influence and opportunities for adoption and feedback.
I’ve worked on the docs for a few open source projects, and it’s hard. 🙂
Here’s what Ben talked about:
- Where docs fit into the user journey
- How docs support users
- Examples and inspiration for docs
These are the types of people who use the docs: potential users (people who’ve heard about the project and are interested in starting to use it), implementers, maintainers, and contributors.
There are a few myths about docs, including that no-one reads, and definitely no-one wants to write docs, yet the docs must exist. Ben says to address this type of thinking, we need to analyse the types of documentation people need, what they want to read. For example, avoid large blocks of text. No-one wants to read them, and writing them is hard.
Docs for new users
Consider how people approach the docs:
- The commitment pattern is very rare – this is where the reader sits down and reads the entire text from top to bottom.
- The layer-cake pattern is more common – people scan for headings and for things that are interesting to them.
- The spotted pattern is where people look for specific items e.g. a specific guide. This is also common, especially when people have used the product before.
Someone starting with the project may ask themselves: Does this project solve my problem, and will it help me with my career? Note that the README will probably be the first doc a person reads. So pay attention to it, and make sure it gives people a good overview and signposts to where to go next.
Avoid saying something is simple, or tell them to just deploy using x. Rather, showcase the project in the smallest amount of time, to help them decide whether the project is right for them. Examples are the best way of doing this. (Short videos and GIFs are often used too, but people have to download and watch them, which may be discouraging.)
Kubernetes, for example, has an interactive element in the website which gives people a feel for the project. Stripe found a significant advantage when they included interactive snippets in their website. Realistic blocks of code where you can see the core aspects of the product working.
A good tip is to include snippets of code in the docs, and link directly to GitHub for people who want to see the rest of the code.
We also need to make docs inclusive. Take care with the examples we use. Respect the fact that not everyone’s first language is English. Don’t use words like “it’s simple” or “just do this”, because for many people it’s not simple. Avoid making the user feel bad. The problem is ours, we need to make the software as simple as possible, and the docs should acknowledge that.
Docs for an active user
Active users of the project have needs that differ from those of new starters. They want to solve other problems, or find a solution for something that’s broken.
We need to focus on how people can find what they’re looking for. Discoverability in the docs. Ben gave the example of the Twilio docs, which ask readers a few questions before deciding where to take them.
If something is broken, consider the user’s emotional state at this time. They probably don’t want to read a lot of text at this time. StackOverflow and GitHub Issues have become key resources for this type of use case. When writing our docs, we need to acknowledge these resources. For example, point people to an issue and make sure the issue is informative.
Docs for community contributors
We must make sure there are good contributor guidelines. Make sure people feel safe, by including a code of conduct. Include a licence so people know the terms under which they’re contributing.
Consider running a doc sprint where contributors can come and talk to project maintainers about becoming a maintainer themselves. Also working groups and contributor summits have huge impacts on showing people how they can improve their contributions to projects.
Three key points from Ben
Developers experiment. The docs should support this mindset.
Users get into trouble. Make sure we provide doc types that support the fact that people encounter problems.
We should encourage contributions. Not only the code base should be open source, but also the documentation.
From Ben: Having amazing documentation becomes your key differentiator.
From me: Thanks for a great talk, Ben, and +1 to fostering amazing docs for amazing open source projects.
This week I’m attending the KubeCon conference in Seattle. The conference’s full name is KubeCon + CloudNativeCon North America 2018. I’m taking notes from some of the sessions I attend. Any mistakes in these notes are my own, and all credit goes to the presenters and to the audience who contributed ideas during the session.
Orna Berryman moderated a panel discussion titled “Growing Diversity in Open Source Projects”. The speakers were Jasmine Jaksic, Lin Sun, and Limin Wang. The goal was to focus on how we can increase the number of people with different backgrounds, skill sets and experience working on open source projects.
The statistics for the number of women in open source communities are around 3-5%. Orna put a question to the panel about why this may be the case. This compares to 20-30% in tech companies. One reason may be that there’s no regulation of bad behaviour in open source, such as instituting a code of conduct. More than 40 000 projects have already adopted one, many of them based on Contributor Covenant.
Another way to tackle the lack of diversity is to say something. Often, if someone addresses a problem immediately, the perpetrator will stop offending.
Imposter syndrome afflicts people starting on an open source project. There are a few ways to tackle imposter syndrome. Label issues with “help wanted”, or some way of indicating that an issue is a good place for a starter to contribute. Also provide mentoring for new starters, and recognise their work.
Communicating remotely can be intimidating. It’s hard to share your thoughts, and sometimes your thoughts are so different from the rest of the community that the community doesn’t appreciate them. (No-one +1s your comment.)
Travel is hard for some contributors, especially those who have young children. This makes it difficult to travel to conferences.
A question from the floor: what about governance? We can’t rely on an honour system. A code of conduct can’t do everything. We need to have governance over the community. The open source projects need to ensure there are members who monitor the behaviour within the community, and to take responsibility for that behaviour. Large organizations, such as the Linux community, should encourage this type of monitoring. The responsibility also belongs to every person in the community. Step in if you see bad behaviour happening.
People hesitate to join communities where they don’t see people who they can identify with. So communities should keep diversity front and centre.
Contributing to the community should be seen as of equal importance as contributing to the code. No matter how valuable someone’s code contribution, or how large their following, we should follow up on any bad behaviour by that individual.
Question from the audience: Is there a community where we can send people who need to create contacts? There are mentorship programs, such as Google Summer of Code for students. Opensourcediversity.org has a number of projects where you can sign up. There’s also outreachy.org for students who want to enter the open source community. and which focuses on diversity. If such programs can pay people, or provide childcare, this will make things easier for people with young children.
From the point of view of hiring new employees, open source contributions are viewed as more important than an internship. Employers should encourage people to work on open source projects, which are equally valuable to their CVs.
From me: Thanks to the panel for an interesting discussion. The points above should be useful especially for new open source projects, as well as for open source contributors.
Last week I attended Write the Docs Australia 2018 in Melbourne. Around 100 documentarians gathered to discuss words, code, style, and other essentials relating to technical documentation. There was plenty of food and fun too.
“What’s a documentarian,” you may be wondering? In Write the Docs parlance, a documentarian is someone who cares about documentation. Documentarians include technical writers and communicators, as you’d expect, but also UX writers, software engineers, marketing content writers, and more. If you think docs are a Good Thing, you’re in. 🙂
Approximately 100 people attended Write the Docs AU this year. Attendees came from Australia, the APAC region, and around the world. The following photo is from the Write the Docs photo set on Flickr:
Talks, workshops, and unconference sessions
The talks included:
- Lana Brindley: Facebook, Dynamite, Uber, Bombs, and You
- Mike Hamilton: Responsive Content – Presenting Your information On Any Device
- Kristine Sihto: The Art of Consistency – Creating an inhouse style guide
- Abhay Chokshi: UX writing – Let your product speak
- Alexandra Perkins: Making Yourself Redundant on Day One – Internal documentation to teach the next hire what you’ve learned
- Matthew Borden: Good Code, Bad Code & Code Review
- Nicola Nye: The subtle art of interrogation
- Daniel Stevens: Creating experiences with information!
- Laura Bailey: Backseat Content Strategy
- Mathew Patterson: Power up your support team to create better documentation
In addition to the presentations, we heard a number of informative, entertaining lightning talks. People could choose to attend one or more workshops and run or participate in a few thought-provoking unconference sessions.
These were the workshops:
- Sarah Maddox: Tech Writing 101
- Sara Marek: Let’s create a Style Guide!
- Jessica Parsons: Static Site Generators, What, Why and How
Tech Writing 101 workshop
Around 50 people attended the Tech Writing 101 workshop, which I ran with the able help of Eric Gilmore.
This tech writing stuff is hard. But fun!
Tech Writing 101 is a two-hour workshop on the principles and techniques of technical writing. It leads the participants through a series of pair-work exercises to improve the clarity, readability, and effectiveness of their writing. You can read more about the workshop on the Write the Docs AU page.
By the end of the session, participants also think differently about toothbrushes.
The workshop pre-reading is available in LisaFC’s GitHub repo. A number of the workshop attendees let me know that they plan to introduce that pre-reading to their colleagues, as it’s a great introduction to the patterns of clear writing.
Photos and videos
Tweets and write-ups
Have you written a report on the conference, or come across someone else’s writeup? Let me know by adding a comment to this page or tweeting @sarahmaddox!
My takeaway from the conference
So many people who’re passionate about docs! It was a privilege chatting to engineers, UX designers and writers, and marketing folks, as well as other technical communicators. Thanks to everyone for a great conference!