My personal techcomm journey – 2016

Standard

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)

Toolchain

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.

Git

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.

wordcloud

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!

Standard

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.

WTD

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

Standard

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

Standard

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.

TWIA1

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

TWIA2

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. 

2002

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.

2004

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.

2005

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

2005-2006

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.

 

Conversation with Janet Taylor, Conference Organiser, TWIA 2015

Standard

Everyone loves going to conferences. Along with learning via presentations on new topics and case studies, it is also an excellent way to find possible work opportunities and meet other similar people. It could also mean visiting a new city, soaking in the sights (if you get a chance) or trying out something different.

Ever given a thought to how a conference is organised and what goes behind getting the logistics sorted out behind the scenes before the delegates arrive at the venue? From the presenters to the venue, from food menus to delegate goody bags, from sponsors to prizes; it can provide some exciting challenges, especially if you are not in the city where the conference is to take place.

I have been fortunate this year to help with finding potential speakers, sponsors, helping out where I can with sending out conference updates to members and whatever else I can assist with. I am even more privileged to work with someone who has been organising conferences for the ASTC (NSW) and now the TWIA for the last few years, and had excelled herself every year. It takes an extreme level of planning and a fair amount of persuasion, diplomacy and efficiency to get the show up in place.

TWIA_logo_icon only

I decided to ask Janet Taylor, the organiser chief for the TWIA 2015 conference and she was more than happy to share her thoughts on this.

a. How long have you been organising the conference?
I can’t remember when I first started organising the conference but it was about 8 years ago. At first it was a joint venture with the late Susan Harkus. She made it such an enjoyable thing to do, that it didn’t frighten me to be involved. In those days we had to do some arm twisting to persuade people to present. Susan was very good at that part.

b. How do you select the conference proposals? What do you look for, in a presentation/speaker?
First of all we start with a theme and then issue an invitation via our publications for people to present. Nowadays we have potential presenters approach us (or me) with an outline of their presentation. If I’m not familiar with a potential presenter, I try to find someone who knows of them or their skill. I also try very hard to meet them but at least I will speak to them on the phone. I can only judge their suitability by the usual things: has someone recommended them, how well they know their selected topic, how suitable the presentation would be. Sometimes I do get it wrong.
I go through the appraisal sheets from the previous years’ conference to see if I can use any topic or presenter suggestions. Otherwise, the program could end up being only about topics that I’m interested in. I do try to maintain an interest in all the TC developments that I can, to try to ensure my interests don’t get too narrow. That’s one reason why I stay involved with Southern Communicator ─ I’m force-fed other viewpoints.
The other thing about a presenter is where they live in relation to the conference. The more locals the better. Less logistics.

c. What would be your worst nightmare when it comes to organising a conference?
I’ve had two worst nightmares: One was presenters offered to sponsors. We knew nothing about them or their presentations until a week or two before the conference and had no contact with them at all prior to the event. Would they turn up? Did they know anything about their audience? In the last instance of this, they were a success but my nerves nearly didn’t last up to the day.

The other was when a presenter contacted me on the morning of his presentation day to say his wife had gone into labour and he simply couldn’t present. I had to agree, I didn’t think he’d be able to concentrate even if he did his duty to us.

d. How easy/hard is it to reject a presentation proposal and how do you do it without losing friends?
I’ve usually had a good reason for rejecting a presentation and it hasn’t been because I didn’t think it would any good. (That might be the reason, but there’s usually some other one to use). Only one person has fallen out with me “You’re a very difficult person to deal with!” Me?

e. What’s the best conference you have ever attended? What made it special?
I’ve attended a lot and I can’t think of one being better than others. The Ark Group conferences (which ASTC members could attend free of charge) were always very good with excellent presenters. I’ve no idea how they found some of their presenters, but it might help that their staff are professional conference organisers.

f. In your opinion, what does a good conference look like?
The venue is the most important factor.
Then the conference room: no pillars, a high ceiling and a reasonable temperature (I’m still waiting for that aspect to be right).
Decent food and coffee.
After that, delegates who are prepared to talk to other people, not just those they work with. I used to be an absolute wall flower so I’m always on the alert for people who aren’t mixing. I can get quite bossy then as I don’t want them wasting their attendance. In my opinion, one of the major benefits of a conference is meeting the other delegates.

About Janet Taylor
After the birth of her son, she decided that she’d need to give up her 24 hour a day IT job (which she loved) and try to find something she could do from home. When she discovered that there was such a job as technical writing, she decided that was perfect for her. She’d always done the user guides and training for all the systems she had developed over the years. In her first job, she had to join a professional society and ASTC (NSW) seemed to be THE ONE. After she’d been a technical writer for about 5 months, the society appealed for someone to handle the marketing. She was certainly qualified to do that and felt obliged to offer her services. Unfortunately, it involved being on the committee and attending meetings. However, 20+ years later, she is still on the committee. (Her son is now 32 years old and she has never yet managed to work from home.)