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:

My personal techcomm journey – 2016


What a year it has been. I feel I have personally gained a lot during the last 12 months in my technical writing journey than I have in the years before.

Now that it is time to unwind a little bit with the holidays well within sight, I’ve finally found some time to put down my thoughts here.

Summary of 2016 (in no particular order)


I definitely feel a lot more confident using a range of tools, largely due to the fact that I could use them for my various projects.

While I am largely stuck using MS Word at work, along with SharePoint for publishing, I’ve had the chance to use Madcap Flare + Git (via BitBucket) for my part-time project with Planifi. In the last few weeks, I also started using GitBook for creating online help for Rounded (an accounting app/tool for sole traders and freelancers) and I think it’s an amazing tool to use for lightweight documentation.

Snagit still remains the best tool I use, day in, day out. It sits quietly in the background and every time I hit the PrintScreen for it to fire up, I feel like Thor calling on his Mjolnir to do some grunt work.

Believers and non believers

This is always a tough one. While my current team and especially my team lead believes in the value of good documentation, there exists some in the larger business unit who do not see any real value in documentation and are reluctant to come to the party, so to speak.

It is always a challenge to make people see the value in documenting, be it processes, systems or pretty UIs, but so far with a fair amount of persuasion and a little bit of name dropping (desperate times!), I’ve been able to get things documented.


I don’t know how doc projects existed before Git. I use Git fairly regularly for my freelance projects and couldn’t dream of having documentation without any sort of .git associations with it.

I work across 2 different devices (a PC and a hybrid tablet/laptop), so picking up where I left is never hard if I have managed to push through my changes to the central repo using Git. I would like to use the Git Bash Prompt to do this, but most days I prefer SourceTree to push doc changes to GitHub or BitBucket based repositories.

Pro bono docs

Ever use a really cool tool and feel you could contribute to their journey? I came across Rounded while I was trying to find something to help me manage my invoices for freelancing projects. Rounded was founded with exactly the same idea – accounting for freelancers and sole traders (and it was Australian based).

I got in touch with the founder and offered to write their documentation for them, simply because I believed I could help them while getting a chance to try out their product for my projects. I have started on the documentation and am using GitBook to create some basic online documentation for new users of the tool.

Write the Docs (meetups+conf)

This was, and is, by far the best thing that has happened to me this year – becoming a part of this large, and rapidly growing, community of people passionate about the art and science of documentation. The community may have started off with a focus on software documentation, but I think it has clearly gone way beyond that.

Growing a little disillusioned with the ASTC and what it offered to members, I admit I was struggling a bit to feel a part of any community (a tribe essentially) and this was when I came across Write the Docs 6 months back. I joined the Slack channel with a little anxiety, but it was and is a great place to be. The amount of ideas and the free-flowing nature of conversations on the Slack channels have been inspirational.

Soon after I connected with the Write the Docs community, I felt it was the right time to get these meetup events to Australia. With a little help and encouragement from my techcomm friends (a big thanks to Sarah Maddox), we kicked off Write the Docs Australia in Melbourne, followed by an even bigger event in Google offices Sydney. The idea is to take the events nationally and hence the next event is scheduled for Brisbane for Feb 2017.

While I was planning to attend the Write the Docs Europe conference, I received notification that my conference proposal was accepted. I thoroughly enjoyed the experience of presenting at an overseas conference and the audience was excellent. I spoke about what bad screenshots do to good writers, largely from experience and also deriving some inputs from other writers.

Flare User Group

All while I was getting involved with Write the Docs, the other group I started 2.5 years back was still around and kicking – the Melbourne Flare User Group. What started off as a local Melbourne event has long surpassed the geographical boundaries and we now have members regularly join in from Perth, Sydney, Adelaide, New Zealand and one from Bangkok, Thailand on Skype.

The group is still going strong and we have covered a number of interesting topics around Madcap Flare. We meet every alternate month via Skype.

API courses

While I had some free time between projects, I signed up for a couple of API courses on Udemy, particularly ones around API documentation. While they are far from being completed, I have liked what I have done so far (have completed the JSON/XML component) and would like to pursue this further. It is definitely on my to-do list for 2017.


To-do list for 2017

Better tools – While I am largely happy with the range of tools I am using, I have enjoyed working with tools that allow me to focus on writing than being worried about the look-and-feel and wouldn’t mind working with such tools more.

I would love to design or collaborate with someone who could create a dashboard for tech writing projects (regardless of the toolchain). A dashboard showing the status, estimation of effort, costs (if that is something that can be easily worked out) and tasks.

Raising the profile of tech writers – This is not going to be an easy task and is certainly not a one-person thing. I would like to get help from as many communicators as possible to raise the profile of technical writers here in Australia. A fair number of organisations still do not understand the value tech writers bring to a project and I would like to work on changing that, if I can.

API docs – I would like to spend some time learning and practicing API documentation. I feel there is a great amount of work in this sphere for technical writers and I want to use my technical skills and experience writing documentation help teams write clear, consistent documentation.

Different projects – Variety is what keeps me going and I love dabbling in different projects at the same time, time and health permitting. This is one of the reasons why I like taking on projects on the side, to keep the creative juices flowing. For 2017, while I may cut down on my project work to dedicate more time to learning, I would still like to be involved in a project of a nature I have never worked on before.

Meetups – What started off in 2016 will definitely continue in 2017 with more techcomm focussed events. The Write the Docs Australia roadshow next rolls into Brisbane and will make its way back to Melbourne via Sydney. Who knows, even Adelaide could be in the mix.

Remote work – This year, I have been lucky to work with a company and a team lead who are extremely flexible with my working style and consequently work hours. I like early starts, so most mornings, I get a lot of work done between 4.30 am and 6.30 am on my freelance projects, before my family gets up. I would like to take on projects that allow me a fair amount of remote work, as it suits my working style.

Volunteering – Last month, someone got in touch with me to ask me if I was keen on volunteer with their organisation teaching kids how to code. While I can’t (or won’t perhaps) code to save my life, I am interested in the challenge because I may yet learn how to teach coding.

This idea could be extended further to get kids aware of documentation from an early age, though personally I struggle to see why my 5.5 year old would want to write more than what is absolutely essential. Those shiny metallic buses and trucks are not going to play themselves!

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.

The ASTC is failing us


Exactly a year to my previous article about why you should be a part of the ASTC, I feel disgruntled and disappointed in the direction the organisation is headed.

Sadly, I was a part of the committee until a few weeks back. I resigned because I didn’t think I was delivering any value to our members. And that, unfortunately, is the bitter truth.

Over the last few weeks, a couple of ASTC members have expressed disappointment on the value the membership provides as well as the lack of communication from the committee. I’ve been a member of the ASTC (Australian Society for Technical Communication Incorporated) for the last 10 years or so (on and off) in its various forms – firstly the state based Vic organisation and then the TWIA/ASTC in its latest form. I agree with the sentiments of these members.

It is not a Australia specific issue. The wider and bigger STC has faced a fair amount of questioning and introspection from its members over the value it provides as it stands today.

I am based in Melbourne and we have a few things going for us the last 2 years, mainly the conference and local events, which have either reduced or completely disappeared from other states. The committee has tried to involve members locally to organise or put their hand up for managing meetups. We (while I was a part of the committee) did not get many responses. You can’t be serious about having a “community” if you do not want to get involved. Suggest an idea, recommend a speaker, arrange an impromptu meetup.

Almost all of the training workshops/events organised have been either Sydney or Melbourne based and I can see why members from other states feel alienated. It is almost as if they don’t exist.

These are a few ideas that I am happy to put out there for debate, discussion and comments:

  • There has not been enough membership drives to attract new members. This needs to be top of the list.
  • The committee structure as it currently stands is not working. To me (and having worked as part of this very same committee), it is outdated and archaic. I understand it is an organisation and it has to adhere to rules, but it is time to look at our charter.
  • Adopt an agile methodology around committee actions/decisions. Similar to successful IT teams, have sprints of actionable items that need to be delivered within the sprint.
  • Separate communication activites from committee memberships. You should not have to be a committe member to help with sending out mailouts or tweets on behalf of the ASTC.
  • Work with the recruitment agencies to form partnerships and value-add for members.
  • Work with other non tech writing organisations (outside the current TCANZ, SOCEDS etc) to have reciprocal arrangements. For example, Content Strategy, User Experience etc.
  • For the next 2 years, cut the membership rates by 50% as goodwill and prove why membership to ASTC is worth it.
  • Provide certificate of appreciation/participation for volunteers if they volunteer for ASTC events (local or national conference).

Down Memory Lane: Graduate Diploma in Technical Communication


At the recently concluded TWIA conference in Melbourne, I met a few lecturers from my Grad Dip in Technical Communication. I have been in touch with some of them over the years and it was good to see everyone together again.


L to R: Gerry Gaffney, Kylie Weaver, Tony Self


With Andrew Lockton

Catching up with them took me a little down memory lane, back when I took the Graduate Diploma at Swinburne University. I am definitely happy that I took and completed this course back then.

The Graduate Diploma in Technical Communications has ceased to exist for the last few years, though I know (and have worked with) a few Technical Writers who have good memories and positive experiences of this course. 


I was working part-time as a Data Entry Operator while studying for my Masters, when my team lead asked me if I was interested in helping the development team over the summer break with testing a product the organisation was developing.
Along with testing, I was also asked to update (and where required create new content for) the user guide that shipped along with the product. I have always been interested in writing, but those 2 months of testing and documentation experience got me interested in the whole documentation process – gathering information, updating, reviews and final publishing. Not without its share of usual issues though – SME unavailability, lack of clear feedback and review etc.


It was during my brief role as a Client Liaison Officer with the same organisation that I had a chance to work on a large database project, a directory that contained information of all hospitals, medical centres and other health services throughout Victoria. Along with managing the communication templates (email and fax), I enjoyed creating some Help/FAQ pages for the service directory, and these documents were well received by the end-users.


Now having progressed to a Data Specialist role, I was working on cleaning, parsing and analysing data while trying to work out the most efficient way to perform these tasks. A fair amount of this work was repetitive, though the nature and type of data varied, which made it possible to document the instructions on how to perform the tasks to clean, parse and outputting the data.
I readily put my hand up to update the Standard Operating Procedures (SOPs) because it gave me a chance to do something that I had only briefly dabbled in the previous years – technical documentation. I had certainly enjoyed the experience then and hopefully could get to do more of this.

While my Masters of Business provided an ideal base for understanding how businesses look at information systems, I was looking for certification or a university course that gave me a core understanding of the technical communication process, tools and practices. Although there were a few online courses that caught my eye, the Graduate Diploma in Technical Communication at Swinburne University fitted my requirements perfectly, primarily because it was local and the curriculum


Looking back now, the Grad Dip at Swinburne was a really well designed diploma. The most interesting (and bit of an eye opener for me) fact was that technical writers come from all sorts of backgrounds. There is no prescribed path for a technical writer.
In our very first semester, we had people from journalism, IT Support and Programming backgrounds who wanted to learn more about technical writing. It was a very close-knit group, consisting of about 5 people in the first semester, and got even tighter, down to 2, by the last semester rolled off.

Tools, Docs, Prototypes and Projects

Kylie Weaver taught us about the 5 Cs of writing, creating effective technical communication and how to go about managing the documentation development cycle in relation to the waterfall model. Agile and scrums were not so much of a thing then.

Sonja McShane delved deeper into the document development process, and got us creating Information Plans, Content Specifications and other technical and project documentation over the semester. I still start off any project by creating an Information Plan that outlines the scope, deliverables, audience understanding and a suggested topics structure. Old habits die hard.

Andrew Lockton took us on a grand tour of the tools involved in creating documentation. From MS Word to Dreamweaver, RoboHelp to Framemaker; it was a really good insight in to how tech writers use different tools to achieve more or less the same result – usable documentation.

Tony Self taught us how to arm and disarm HTML documentation, creating online help for applications. Using his vast knowledge of the hyperlinked world, he showed us how to go about creating structured chunks of information, assembling them together and making them behave via hyperlinks. He also showed us how to go about embedding our deliverables with the product code, while playing along nicely with the developers and testers to get it done.

In the second year, Gerry Gaffney got us thinking about usability and user centric design. In his own encouraging style, he made us look critically at websites, how content was delivered over this medium and how effective the content was. We got our hands dirty, using affinity diagrams, prototyping and creating usability reports for a fictional case study. I absolutely loved the project we created and delivered, because it gave us a very practical understanding of usability principles.

During the last semester, we (having dropped from a promising 5 to a bare minimum 2) were entrusted with the task of managing a documentation project. This involved using all of the knowledge gained over the preceding 18 months and coming up with an Information Plan, a technical document (User Guide or Online Help) and submitting a final report around the project milestones and deliverables. We tracked resources, timelines and milestones using Microsoft Project, collaborated on ideas for products and delivered a comprehensive project report as our final assignment.

2006-2015. And beyond.

While I was in my last semester, I got my first official gig as a Technical Writer, creating compiled help content for a radiology information system.

2015 and I am still here, creating technical documents and loving it.