A year of documentation goodness


Today marks the 1 year anniversary of the Write the Docs Australia community. We’ve come a long way and have even a longer way to go yet. 300+ members and counting.

A big thanks to everyone who has made this possible – attendees, speakers and hosts.

Where it all began…

To me personally, Australia seemed to have fallen behind in organising meetups, conferences or any events around documentation. We don’t even have any university level programs teaching the basics of documentation. There is an ever increasing demand on creating clear, consistent and useful documentation and we just didn’t seem to be doing enough to address it.

I came across the Write the Docs community when I was looking for a group to network, a place to belong and a tribe to identify with. Having heard of the Write the Docs Prague conference, I put in a presentation proposal which was accepted and I was on my way to the Czech Republic.
When I first signed up to the Write the Docs Slack channel, there were just about 700 people in the #general channel, and just about a dozen in the #australia one. (For reference, they now stand at 2206 and 67).

Here was a community that had its roots in developer/software docs, but had expanded over the years to include anyone who created, appreciated and understood the value of documentation.

Sometimes, as they say, the best way to be involved is to start something. So, I initiated the Write the Docs Australia meetup group on July 20, 2016.

Looking back over the last 12 months, it has certainly been an exciting ride.

Tribe of documentarians

Anyone who cares about the quality of documentation and its impact on the users is someone we think of as a documentarian.

Over the last 12 months, we have had 7 events across Australia. 2 in Brisbane and Melbourne, and 3 in Sydney. The Adelaide one is not far away.

With a little help from the wonderful Content Strategy and User Experience friends, we are headed to Write the Docs Adelaide on 7th Aug.

The very idea of having an inclusive, vibrant community of people who create documentation as part of their roles drove us to talk about all things documentation.

  • We talked about APIs, Interacting with Developers, Roles in Product teams, Visual documentation, Analytics, Doc-a-thons, Localisation, Markdowns, Storyboarding, Data, Product Development docs and more.
  • We had writers, developers, UXers, QA, Product owners and Engineers attend, network, speak and share their experiences.
  • We got some solid support from companies like Google, Atlassian, Campaign Monitor, General Assembly, Red Hat, and River City Labs who hosted our events and sponsored food/drinks generously.
  • We streamed most events live and almost all recordings are available on the Write the Docs Australia Youtube channel

This slideshow requires JavaScript.

What’s coming?

The first ever Write the Docs Adelaide takes place on Monday, 7th Aug. We are already planning for events across Brisbane, Melbourne, and Sydney in Aug and September.

A 1-day mini conference sometime late November is already beginning to sound like a possibility.

A very wise person (Eric Holscher) once said:

Write the Docs meetups, now in Australia!


At the start of 2016, through various sources, I discovered the Write the Docs community. Best thing that happened in my professional life. I was vaguely aware of the Write the Docs movement (and that is what it is), I decided to get involved because I was getting disillusioned by the other tech writing body I have been working with (the ASTC) for a number of years. I knew a few Australian based writers who were already a part of this community and their feedback was encouraging.

“Write the Docs is a series of conference and meetups focussed on all things related to software documentation”, is how the website describes it, but I suspect it has matured beyond software documentation. It is a rapidly growing community of anyone associated with, or involved with documentation, be it developers, customer support, technical writers or product managers.

While the Write the Docs has 2 conferences every year, one in Portland, Oregon (US) and the other in Europe (various locations), the community is also supported via a number of meetups hosted across a number of cities in US and Europe. It was time to get the Write the Docs to Australia. Our first Aussie WTD meetup took place in Melbourne on 9th Sept 2016.

Write the Docs Melbourne Sept 2016

The ever affable and enthusiastic Sarah Maddox accepted my invitation to speak at our first meetup and even flew down from Sydney specially for this. Thank you Sarah!

In her presentation, Sarah gave us the low-down on how to work with engineers to create, collaborate and produce API documentation. She stressed the importance of getting to know the engineers, their interests and participating in work activities such as hackathons with engineers.

During Sarah’s talk, she got the meetup attendees to live collaborate on a document she had shared before her presentation. At the conclusion of the talk, she discussed the comments from the live documentation. This was a way to demonstrate how tech writers and engineers collaborate on content.


After her talk, I gave the attendees a preview of my conference presentation on “When bad screenshots happen to good writers”. It was well received and I got some good tips and feedback on the presentation material.

The WTD Melbourne meetup has now over a 100 members who have signed up in a space of 6 weeks; members across a variety of professions and backgrounds, interested in the art of documentation.

What next?

Got an idea for a presentation? Know someone who is keen on sharing their knowledge of awesome documentation techniques? Have a burning documentation issue you need to address with fellow documentarians?

Get in touch with me through the WTD Melbourne meetup page and we can schedule something.

ASTC Event: Managing your personal brand


I attended the local Victorian event organised by ASTC (www.astc.org.au) last Thursday (17-Mar). Chris Clarke from M&T Resources and co-founder of yourcareerhouse and has a strong 15 year background in sales, publishing and recruitment.

He shared some really good insights on the recruitment industry in Melbourne and ideas on how to build a strong personal brand leading to more opportunities.

In his presentation, Chris spoke about 3 things:

  • Resume Tips
  • Your personal brand
  • How to manage your recruiter

Resume Tips

It is safe to say that Chris goes through a fair amount number of Resumes. Every single day. In fact, in his experience, a lot of jobs these days see a minimum of 200 applications. A lot of these Resumes are not tailored to the job advert and are very general in nature, making it hard for them to stand out.

According to Chris, a recruiter has only up to 6 seconds to make up their mind about pursuing an application. The Resume should stand out on its own against 100+ other applications. A potential candidate may miss out on a good opportunity only because they cannot sell their skills effectively via the Resume. How do we fix this?

Tailor your Resume
It has probably been said a million times before, but Chris reiterated the fact that you need to tailor your Resume to fit the job requirements. Sure, it may seem like you are spending a lot of time tailor-fitting Resumes in the job search process, but if you really need that job, you will at least need to make an attempt to show that you are serious about it. The first place to do this is to have a Resume that specifically shows your skills match the client/job requirements.

The trick, according to Chris, is to lock away yourself for a good 3-4 hours to create multiple templates of your Resume. Templates that can be used to have tailored or personalised versions of your Resume. Whatever time you spend in a day (working out templates) will pay healthy dividends later.

A short and crisp Resume is a good Resume
Chris shared another insight from his experience working overseas and now Melbourne. He strongly believes Melbourne is a relationship driven city and it is about who you know more than what you know. Unlike in US or UK, recruiters here don’t mind seeing Resumes that go 4-5 pages, so long as they stay relevant. A 1-2 page Resume is great if you can fit everything on it.

One of the most common questions, posed especially by contractors with a lot of projects under their belts or industry veterans is around how much to put on a Resume. Chris recommended putting experience worth the last 10 years on a Resume and then talking about other experience when it comes to face-to-face interviews. Given the pace of technology and innovation across all fields, it is often advisable not to include experience from over 20-30 years, as they become obsolete pretty quickly.

Your personal brand

Chris reckons Linkedin is essentially a digital CV these days. Most of the recruiters or hiring managers turn to Linkedin first to find out more about an applicant before going down the phone or email path. Setting up and updating a Linkedin profile is easy; it is what you put on there and the way you tell a story is what sets it apart from other similar profiles. A good recruiter looks beyond the work experience and sees more of what value a applicant brings to the role.

How do you go about creating/selling your personal brand?
Chris suggests having the following information on Linkedin to add to your personal brand:

  • Treat the summary as an elevator pitch summarising your skills and experience and what value you can bring to an organisation.
  • Instead of merely listing down job responsibilities from previous roles, write a story about who you are as a person. Everyone loves a good story.
  • Mention what you are up to outside your work. Blogs, meetups, volunteering projects, community activities. This clearly shows how you are building your professional equity and becoming a thought leader in your area of expertise.

Manage your recruiter

Recruitment is not a one-way street and there is certainly no master-slave equation these days, says Chris. A good recruitment relationship is bi-directional and beneficially mutual.

Recruiters are essentially filters between clients and candidates and are good at relationship management, which is what makes them the ideal medium.

Working with recruiters
Chris shared some tips on how to get a foot in with your application:

  • After you have applied for a role, you are entitled to call the recruiter 24 hours later about the application. They may not respond right away, but your name will be on their minds when they get to the applications.
  • Sometimes, you could have all the skills, but that does not mean you should get the job. Culture fit is a very important criterion these days, so consider this when you apply for the role.
  • It is perfectly ok to call the recruiter and ask to meet them. This is a good opportunity to meet face-to-face and also explain what you do and what you can bring to the role.
  • You can ask the recruiter questions such as
    a. Do you understand what I do?
    b. How am I looking against other applicants?

Tips to engage with recruiters
Chris recommended the following strategy if you are in the market (or even otherwise) for keeping the job market and opportunities on the radar.

  • Engage with 2 big recruiters to know more about opportunities/openings across bigger organisations. Chris spoke about how big companies usually have a panel of 5-6 recruiters, so your chances may be hampered if you apply for the same role through different recruiters.
  • Liaise with 2 medium consultancies for roles across small-to-medium organisations.
  • Be on the books of a boutique (specialist) agency that specialises in tech writing or complementary areas.
  • Apply to companies directly. It never hurts to contact hiring managers at companies you want to work for directly.

And finally, when you do catch up with a recruiter for coffee, never offer to pay. Recruiters can and will usually expense it, says Chris.

Networking event: How to land a job at top tech companies


In a market of ever changing dynamics, requirements and start-ups, how do established tech companies manage to find the right candidate to come work for them? As a candidate, are you doing anything different to catch the eye of the recruiters for these top tech companies?

I have been attending networking events in and around Melbourne since February 2015 to try to get a better understanding of the Melbourne tech market. Last month, I went to the ThoughtWorks Open Office event.

In March, I attended a networking event How to land a job at top tech companies and it was a very informative evening, hearing from talent seekers (be they CIOs, recruitment managers, HR or freelancers).
On a windy and cold Melbourne night, the General Assembly campus room made for an ideal casual setting. Around 100+ people with various skills and backgrounds attended the event.

Who was on the panel?

Chris Regan, Head of People Experience, Xero
Nigel Dalton, CIO, REA Group
James Law, HR Director, Envato
Shai Roitman, Talent Aquisition, Isobar
Ryan Blunden, Freelancer

What do tech companies look for in candidates?

You may think having tons of experience or knowing every skill there is will easily land you a job in a tech company. Sure, in some cases, that might just do the trick, but surprisingly, a large number of tech companies look for other things when it comes to recruiting good candidates.

The following 3 were discussed earnestly by the panel:

a. Constructed chaos – More often than not, a number of tech companies are looking for someone who can come in and make sense of the different things that happen in an organisation. Tech companies are looking for someone who can construct a meaningful picture out of chaos.
b. Cultural fit – Many candidates are increasingly getting rejected because they are not a cultural fit. It is important for a candidate to understand the team/organisation culture and to best demonstrate how they can fit within this.
c. Values – Another aspect that tech companies are interested in finding out what values the candidate brings to the organisation and in return, how closely these values are aligned with the company values?

So, do you have these skill-sets? Chances are, tech companies are looking for you more than ever before.


Experience Design
Front end developers
Product Managers
Ruby developers
Data analysts
UX Designers
Developers iOs and Android

It’s a good thing to have the skills and knowledge of the market, but the million dollar question that was on everyone’s mind:

Where do tech companies look for talent/people?

Not surprisingly, LinkedIn is one of the most popular mechanism for recruiters to head-hunt for talent. Almost everyone on the panel agreed to having used LinkedIn when it came to looking for talent that matched their requirements. Even before some of the jobs were advertised anywhere. So, it pays to have a well constructed and effective LinkedIn profile.

Referrals also form a large part of recruitment, so it is important to know someone who knows someone you want to know. Tech companies are no different when it comes to offering rewards (some times up to $2000) for good referrals. The trick is to get to know people in companies where you’d like to work, which is where networking events come in very handy.
Along with this, popular sites such as Seek, MyCareer are frequently used for advertising opportunities and looking for suitable candidates.

Headhunting for candidates and using recruitment agencies form the fourth wheel of the recruitment wagon, so it is important to build effective networks where you can pick up information on upcoming opportunities.

Oh, and by the way, check out http://www.theloop.com.au if you want to build an online portfolio of your work and get some work coming your way in that manner.

Great, so, you’ve got a well-built LinkedIn profile and have an impressive Resume and a Cover letter, but are you doing anything different that will make you (and your skills) stand out from the rest of the competition.

Want to know a few handy tips on how to approach tech companies?

a. Do something different – Much as cliched this sounds, companies really notice when you approach them with something different than just the usual Resume and Cover Letter. Send a handwritten application maybe. Present your skills online. Create a short video and show how you could work in their environment.

b. Meetups – There are always people out there who want to socialise, talk and discuss common issues, fixes, tips and tricks. Join a meetup and attend one of the meetings to see what others in a similar role are doing differently (or not). Contribute by helping others solve their issues and get noticed by people who matter. Or better still, start a meetup.

c. Community networks – There are a large number of communities that thrive on sharing skills and knowledge. Even opportunities in some cases. See if you can get to know people and build a professional network of similarly skilled individuals.

That’s all good for people who want to get in to tech companies.

What would the panel say are traits that keep talented people there?

The panel members discussed the need to keep talented people in an organisation via various methods, be it be rewards or new challenges. As someone who wants to stay with a tech company, organisations crave for individuals who are hungry, passionate and want to keep learning. One panel member had a very interesting point to make about making time to read, even in the workspace. Far too often, as technical people, we tend to pick up bits of information to apply to a problem, but never go beyond that to understand the whole concept. The panel member advocates taking time out to read.

Soft skills and a good attitude are an absolute must to be able to keep performing in highly agile organisations. Plus, it is very important to keep having ongoing conversations about career with the organisation.

Where is the future going with tech companies?

A large number of panelists are organisations that have a strong online presence, either through their clients or via their products/services themselves. A lot of opportunities have sprung up in the mobile space, especially iOS and Android development.
Resultantly, this has created a lot of demand in design, product management and analysis areas.

And finally, 1 piece of advice from the panelists:

“Learn the fundamentals. Do what you love” – Ryan Blunden, Freelancer

“Get out there and meet people” – Chris Regan, Xero

“Have valuable conversations” – James Law, Envato

“Start a meetup” – Nigel Dalton, REA

“Don’t just work for money, do it for passion” – Shai Roitman, Isobar

When Dr Hackos came to town…


During some of my last few projects, I’ve used help authoring tools to create content in different formats (print, online, mobile devices, embedded help files), all using single sourcing principles. Quite a few clients/employers I’ve worked with in the last 2-3 years have embraced or have been open to the idea of single sourcing and are confident it can work for their content needs, so it has been fairly easy to persuade them to invest in good help-authoring tools that will allow them to make this ‘leap of faith’ from ad-hoc documents to single sourcing content.

I was first introduced to the term “single-sourcing” by my lecturer Tony Self in one of his classes on Developing Online Help for Applications, when I was completing my Graduate Diploma in Technical Communication at Swinburne, 9 years back. As part of this same Diploma, I distinctly remember pursuing a book by Dr Joann Hackos about managing documentation projects, for another class by Sonja McShane on Developing Technical Documents. The book covered (and to an extent, still does) almost everything related to planning, prototyping, creating, implementing and wrapping up a documentation project. The book was first published way back in 1994 (a recent edition covers more relevant topics), but it has pretty much been the cornerstone for many a technical writer, especially when it comes to managing multiple documentation projects and deliverables.

Imagine my delight when I heard that Dr Joann Hackos was going to speak/present at an event in Sydney on 19th June 2014. I had no hesitation in booking my tickets for this 1-day conference, because I was confident of finding something useful throughout the day.


Technical Communication Framework for the 21st Century (Robert Phillips)

In the opening address to the event, Robert Phillips spoke about the Technical Communication Framework for the 21st century.
In terms of Professional Development, the technical writing profession is stuck in a cyclic path wherein the Technical Communicator is in a constant flux of “Start, Learn, Develop”, across projects. In terms of growth, TCs can often learn tools, then the techniques and then the discipline of the profession itself.
There is a strong case for finding good mentors in the industry and also a solid training framework to support the new TW in the 21st century. The glue that holds all of this are the conferences, society journals, trade displays and magazines and hence it is necessary for technical societies to keep this culture alive.
He stressed the need for appropriate training, certification, access to good courses and fostering good techniques which is currently lacking in the TC industry in Australia.
Slide Deck

Information Development in the 21st Century (Dr JoAnn Hackos)

In her first presentation for the day, Dr Hackos gave us an accurate picture of the nature of information development in the 21st century.
Some of the key challenges facing the information development process right now are challenging work environments, global customers and collaborative efforts, pressures to reducing costs, changing skill sets, new tools and standards, disciplined work practices and technical proficiency.
The future information developer will need to pick up a few smarts and likely have more than one of these following traits:

  • Innovative
  • Discipline in development
  • Expert in technology
  • Collaborative team member
  • In-depth global customer understanding
  • Highly resourceful and assertive
  • Superior communication abilities
  • Political and business savvy
Key takeaway

TCs may, if not already, turn into curators of information due to crowdsourcing/user-generated content. Content and more importantly, the way it is delivered, is what is making it interesting.
Slide Deck

Single Sourcing in the 21st Century (Dr JoAnn Hackos)

In this highly useful talk, Dr Hackos started off with this statement “Manuals are not books and product users are not readers. Users need information to perform certain tasks or meet certain goals“. Content has come a long way from books to the online media, though some of the basic concepts of topics, chapters, sections or hierarchies have been carried over.

Dr Hackos then went on to explain why single sourcing is a good idea for businesses and how DITA can step up to fill this niche. Some of the things that DITA does well:

  • It supports structured writing standards
  • It encourages information relationships
  • It promotes repurposing
  • DITA topics enable reuse, and
  • It simplifies translating and publishing
Key takeaway

Single sourcing leads to a shift in the way TCs can approach content. Content itself becomes more important than the formatting, so it is essential to future proof content as well as include value in content.
Slide Deck

Roadmap to DITA

Dr Hackos’s Roadmap to DITA talk started off with a very valid statement “If you don’t know where you’re going, any road will do.” She spoke about a few important things (amongst others) that would see a DITA implementation go a long way.

I could relate to some of these, based on my experience working with single sourcing:

  • A strong business case to get management support
  • Avoid too many stakeholders.
  • Choosing the right CMS. Not every CMS can fulfill the organisation’s requirements. Spend the right amount of time to research a suitable fit for your organisation. She recommended a Component CMS, one that allowed sufficient control over separate components for the content.
  • A well-designed publishing pipeline
  • Collaboration is essential
Key takeaway

One of the real impediments to taking up single sourcing is resistance to change. It is essential to build a strong business case for to help realise it’s value and encourage everyone to embrace it.
Slide Deck

Single Sourcing Tools in the 21st Century

In this tools-based event, 4 presenters gave quick 5 minute overviews about the key single sourcing tools currently available in the market:
a. AuthorIt
b. Madcap Flare
c. Red Hat Open Source
d. Adobe Technical Communication Suite

Content Management in the 21st century (Dr JoAnn Hackos and Dr Annette Reilly)

I missed the first 5-10 minutes of Dr Annette Reilly’s presentation on Standards (see why below – Lunch), but she spoke about the new and existing standards by ISO and IEEE, particularly ISO/IEC/IEEE DIS 26531.2. Later, Dr Hackos gave us a rundown on managing a CM project. This mirrored some of the content from her book, but applied more to a content management project than just technical documentation.

She also expounded on the benefits of using a Component CMS, from her previous talk about Single Sourcing. A Component CMS is specifically designed to support total information development lifecycle and manage components simultaneously as both independent resources as well as part of a larger workflow.

A Component CMS supports:
a. Structured topic based authoring
b. Single sourcing
c. Topic based re-use
d. Multi-language publishing
e. Metadata
f. Search
g. Release Management
h. Interoperability

Key takeaway

While the principles of managing a documentation/content project has not changed over the years, what has changed is the nature of the content and the way it is delivered. Having the right tools (Component CMS) will make the transition from disparate, stand-alone documentation to single-sourcing, a more pleasant experience.
Slide Deck

Communicating in the 21st century (Dr JoAnn Hackos)

In her last presentation and perhaps the most relevant to TCs in this day and age, she presented some startling findings about the impact of social media on content. Based on a survey conducted about industry trends, social media as content strategy and user-generated content, the following findings reveal how and why TCs need to change their approach to content:

Social Media trends:
a. YouTube –16% to 32%
b. Wikis –15% to 22%
c. HTML –23% to 80%
d. PDFs – 90% down to 74%

Customers are even more demanding:
a. 64% ask for content on mobile devices
b. 54% want videos
c. 55% ask for topic-based content
d. 43% want embedded help

Having said that, there were some real barriers to digital publishing that we need to address, and quickly:
a. Content not ready to move forward
b. Lack of experience in creating online content, new technologies, new tools
c. Lack time, resources and funds
d. Disorganised content

To succeed with social media, we need to:
a. Establish a clear social media strategy
b. Set proper governance and standards
c. Integrate social media across information development process
d. Use tools and infrastructure to monitor social media

Key takeaway

Social media is rapidly impacting the way we create and curate content. As TCs, we need to be engaged in the monitoring process, else we risk losing a great opportunity to interact with customers.
Slide Deck

Lunch at Google Sydney offices

It’s good knowing people in big companies! I got a chance to meet fellow tech writer Sarah Maddox for lunch at the Google office in Sydney. Although it was a bit of a mad dash across town to get to/from the Google office, it was well worth it.
Sarah and I have met only once before in person, when I was in Sydney for the Atlassian Doc Sprint in 2011, we’ve been in touch regularly through emails. I’ve also followed her blog religiously, because she has a highly effective and easily understandable way of explaining things and her blog is a great way of learning new things and hearing about first hand experiences of conferences she presents at/attends.
Google offices have a great vibe to them (so I’ve heard) and I think one of their hiring criteria must be that you have to be cool. Their cafeteria is located on level 6 and it overlooks the magnificent Pyrmont Bay. Over a sumptuous spread of a mix of fresh dishes, salads, desserts and handmade juices, Sarah and I quickly caught up on what we have been doing since we last met. It was great chatting to her in person and she is one of the most pleasant (aren’t all TW’s?) people you will ever meet. We discussed single sourcing, wikis, API documents, online help, conferences, tools and would have chatted on the whole day, had I not been strapped for time to get back to the Dr Hackos event.

A nice way to end the day

Adobe had organised a competition at the Dr Hackos event, where you had to string a phrase/sentence including the words “Technical Communicator” and one of their TC products. I put in “Structured documentation is where Technical Communicators meet their (Frame)Maker” and won a prize. A licenced copy of Adobe Technical Communication Suite 5.

Not a bad way to end the day.