About Sarah Maddox
 |
I am a technical writer at Atlassian in Sydney, Australia. I love writing the documentation for products which ooze quality. And I enjoy the contrast in the different products I’m documenting at Atlassian.
|
The weirdest thing I’ve ever written
An article about the Hash, published in Fair Lady magazine. No, not encryption but… see for yourself.
The most rewarding thing I’ve ever written
Face Technologies is a small software company in South Africa, producing cutting-edge biometric applications. They developed a pension payment system which solved a lot of problems for a lot of people. In the poorer parts of South Africa, many pensioners have to collect their payouts in cash. Also in the poorer parts of South Africa, many people are keen to collect payments meant for someone else! Face Technologies developed a biometric payment system. So now pensioners can identify themselves by fingerprint plus smartcard. I wrote the user documentation for the payment system, and some other interesting stuff for Face.
The first document I created from scratch for Atlassian
The Crowd team at Atlassian released Crowd 1.1 soon after I started work there. This release includes CrowdID - an awesome OpenID provider. I wrote the CrowdID User Guide. Our documentation is a team effort, written collaboratively on Confluence, Atlassian’s killer wiki.
Hi Sarah ,
Hey I interviewed for a tech writer job at Atlassian in about Mar 06 and missed out. But I went on to another role at a professional services company where I still am, so it was OK.
Anyway there is a very good chance that this company is going to become a Confluence User. I can hardly wait, it will make my life a lot easier around here!
If it goes ahead I’ll drop you a line.
Jonathan
Hallo Jonathan
What a shame you missed out on Atlassian. I’ve been here for about 8 months now — it’s very interesting, challenging, busy and fun. It’s great that you’ve found a good position too!
Awesome that your company is thinking about Confluence! Let me know how it goes. Have you guys attended a webinar yet? If not, we should let our presales team know that you’re interested in the technical documentation side of wiki-use, as well as the collaboration side. They can then tailor the presentation to be slightly more technical.
Cheers
Sarah
Hi Sarah,
I’m not sure if this is the right place to post but I wish to consult your opinion in this. I’m currently working in an organization that is introducing Confluence to improve it’s collaboration culture. The organisation already has 2 knowledge repositories: an intranet and internal file server for housekeeping all its documentations(technical and biz workflows). Confluence is introduced for its collaborativeness.
So, I’m just wondering if it’s wise to move all the large volumes of existing documentations to Confluence? What about the new documentations? Should we create spaces to store the new documentations?
Thanks
Jovan
Hallo Jovan, it’s good to hear from you
Great news, that your organisation is deploying Confluence. It’s a tricky question, just how much Confluence is suited to document management. Here are my thoughts, but do ask around or contact Atlassian if you’d like more assistance 
The solution you choose depends on a lot of things, including the type and amount of previously-existing documentation you might consider porting to the wiki.
* As a generalisation, my feeling is that it’s probably not worthwhile moving existing documentation to Confluence. It’s not a documentation management system as such. You can attach existing docs to Confluence pages, but why bother if they’re already well managed elsewhere.
* Confluence for new documentation is a great idea, depending on the type of documentation. Confluence is excellent for collaboration, teamwork, discussion. It works well for technical documentation, especially when multiple contributors to the content. But a wiki is not so suitable for documentation which is primarily viewed offline; or documentation which needs very formal formatting or structure (e.g. for legal or compliance reasons); or documentation which is single-source documentation for multiple output formats. (This last point is debatable - Confluence in particular provides PDF and HTML exports. But it’s not primarily a single-source tool like RoboHelp etc.)
Before making a final decision, you’d need to assess the CMS (content management system) you may be using for the intranet (e.g. SharePoint, Documentum, Lotus Notes, something else) and the document management procedures applied to your file server (version control; permissions; publication workflow; etc). Are they doing their job well? If not, then there is a chance that the wiki would do it better. Confluence is targetted as a ‘corporate’ wiki, which means it does have some doc management features.
Anyway, I’d suggest you start by having fun with Confluence. It’s quite rewarding to use
Hi Sarah,
Thank you for the useful advices
I’ve seen your technical documentation for Crowd and felt that it is fantastic. You have structured your content neatly and I have no difficulties in navigating around your contents. I was thinking of creating templates for documentations so that my fellow colleagues can easily create documentations.
Based on your views, I’ve other problems in thought:
* Our organisation has been experimenting with Confluence for quite a while. Different departments adopt different approaches in using the CMS and Confluence. It appears that some departments are actively using it for their new documentations in Confluence while others are still using the existing CMS. I find this a problem as the same types of information can be found in either of the two platforms. It seems quite unstructured and messed up. Should our organisation decide which kinds of documentation should be stored into which knowledge repositories(CMS, Confluence)?
* For some of the employees, they have continued to use the current CMS as their means of documentation and duplicating their work into Confluence (even if it means adding attachments!), which they feel that there is a waste both in time and effort when there is a need to update the documentations. How should I go about this?
* How about training in Confluence? Is it a great idea? I’ve read the website on wiki patterns where it states that providing trainings won’t solve the problem. But I was wondering that employees might not even used it correctly if they are properly trained. I was thinking that training not only provides the necessary skills for the employees, it also creates their awareness as well.
What are your views on these?
Sorry if I sounded too naggy, but I’m just seeing more problems than benefits in Confluence. I really feel that Confluence is a great platform, just that our organisation ain’t using it purposefully.
Thanks
Jovan
Hiya Jovan
Ah, your story of different CMSes spread throughout a single organisation does ring a bell! I think it’s fairly common, especially in larger organisations with many different departments. The very same thing happened when we introduced Documentum in a company I worked for previously. People were very reluctant to abandon their file shares. Then we added SharePoint to the mix too!
Yes, it’s a good idea to decide which type of content fits where, and then publish some simple and clear company-wide guidelines. My previous comment had some ideas of comparing Confluence to a document management system. Also some of my previous posts with the tag ‘wiki’ might be useful.
Have you seen Wiki Patterns? It has some very useful ideas, particularly around getting a wiki adopted by your company and how to deal with some common problems that may arise. Here’s a link:
http://www.wikipatterns.com/display/wikipatterns/Wikipatterns
Check out the Adoption patterns.
A bit of good training never goes amiss either.
I’m glad you like the Crowd documentation — you made my day
Sarah
Hi Sarah,
Thanks for all those tips that you’ve shared with me. I’ve read the Wiki Patterns and felt that those adoption patterns are indeed useful! I might just buy Stewart’s book for more knowledge
Thank you once again for all those kind advices. I really appreciate your help.
Jovan
Hi Sarah.
Thanks for the blurb about Face Technologies. Very kind of you.
Congrats on the new job. It sounds as if you;re having a great time over there!
Cheers,
Werner
Hallo Werner
I’m missing you guys at Face Technologies, but Oz is a great place to be!
Nice of you to drop in
Seeya, Sarah
Hi Sarah,
I wonder how much of the “technical” information you are writing? or is it the developers that are writing most of it? I have been working a couple of months with the documentation for a software company. They are also publishing the documentation at a wiki and I am the editor for one of their products.
What are you daily routines within your job? I read your blog and got a lot of good tips from that. Thank you! Are you an engineer and understand the products you are working with?
Hi again Sarah,
do you have any good tips for writing guidelines for technical documentation internally for the developers?
Hallo Sara,
It’s a good question: How much of the technical documentation does the tech writer write?
The answer depends on your definition of “technical”. In my experience, the tech writers write things like configuration guides, installation guides, administration guides and of course user guides. A lot of this is highly technical. Usually, the API documentation is written largely by the developers — just because that’s the most efficient way of doing things. The tech writers kick things off, by providing a framework for the documentation and asking the developers to fill in the gaps. Then the tech writers review and update the content.
When you’re writing guidelines for the developers, I guess my biggest tip would be: Keep the guidelines short (developers tend not to read them); do things by example i.e. just go in there and set up the framework for the documents; let the developers know that you know that they can write; and encourage them to come to you with questions on style etc.
Good luck
Sarah
Thank you for the good answers Sarah!
I sometimes feel that there is to little time to really understand the product I am working with. I also review and update the content as you do. I add new pages but it is the developers who write the text. I add templates to keep the structure consistent where it’s necessary.
Do you have any other tips to be inspired from except from your blog and the documentation you are writing?
Regards
Hiya Sara
It sounds as if you are doing just fine
The only other tip I have, is to surf around the blogs and other communities — which you’re already doing. One place to try for interesting discussions is http://thecontentwrangler.ning.com/
Cheers
Sarah
Hello Sarah,
Just wanted to pop in and say I’m an admirer - I think you’re doing an excellent job at Atlassian (I see much of your work in the Confluence pages). Do you ever get to attend any User Group meetings? I’m hoping to attend the NYC meeting in September. It would be nice to do a handshake if you make it!
P.S. I’ve added some of your blog links to my own repertoire of bookmarks for when I have a chance to do what I dream of - creating a better embedded help area for our site. I’m just eagerly awaiting the hiring of a new product manager.
Good day and thank you for all the great work in Confluence documentation - I’m still trying to Champion the use of a wiki at our organization.
Hallo Shirley
Thank you for your kind words
I won’t be at the NYC User Group meeting, alas, mainly because I’m based in Sydney. It would be great to say Hi in person some time though, and you never know when that might happen!
I do hope you get to use a wiki in your organisation — it’s a lot of fun. I took a quick look at your dataMentor site. Very impressive.
Thanks for dropping in,
Sarah
I, too, am a tech writer. Please email me privately, as I have a work related question.
Thanks,
Terri
I thought your name sounded familiar … I applied for a job at Face shortly after you left and am pretty sure I saw your name on a doc they showed me after the interview. I remembered being impressed with your use of embedded bookmarks. I didn’t get the Face job, but got a good job at a major ISP soon after. Meanwhile, those bookmarks inspired me to learn everything I could about Word styles and indexing, and now I’m teaching others. So thank you
Hallo Rupert
It’s great to hear from you. I wandered over and had a look at your blog Orion Spur. Wow, you cover a wide range of very interesting topics.
Small world
Good day,
I’m planning on enrolling in a Technical Communications Masters program here in Denver, Colorado, USA. Before I make the huge commitment to not only change careers before I hit my 40’s, but commit the time and treasure to the program…is a career in technical writing a good choice?
Currently, I’m a 15 year professional video producer, working mainly with clients in many different industries, to craft video presentations within their established marketing strategies. Corporate video, if you will. As the economy here has decimated video production opportunities, and as I compete with the young whippersnappers coming up with tools never available to me when I started out…I figured switching to more writing (a task many young video jock loath) is a good idea, both because I love to write, and I have what I would think is a good background.
I would appreciate your advice, or any of your fellow colleagues, about my decision. I understand you being in Australia may not enable you to speak specifically about the climate here in the US, but I would appreciate your thoughts anyway.
Respectfully,
Garrett Evans
Hallo Garrett
I thoroughly enjoy technical writing, and for me it’s the best career choice ever.
It’s quite intense — tech writers tend to get in the zone and work many-hour days. There’s a lot of variety, so most people can find an area or role that suits them. There are also good opportunities to keep up with the latest technology. You do need to keep riding the wave, if you want to stay on top of the job. New things are happening all the time, and that’s where the interesting jobs are too. Those young whippersnappers have the right idea
There are a few community sites on the web, where other tech writers might be able to give their views too. For an overview of what other tech writers are up to, try writerriver.com. There are quite a few discussion groups on thecontentwrangler.ning.com — you could even start your own group or discussion there.
Good luck with the decision. Tech Writing is the place to be