About Sarah Maddox
 |
I am a technical writer at Atlassian in Sydney, Australia. I love writing the documentation for products which ooze quality.
Twitter: http://twitter.com/SarahMaddox |
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
jonathan
20 February 2008 at 2:44 pm
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
ffeathers
21 February 2008 at 7:21 am
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
Jovan
28 February 2008 at 6:25 pm
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
ffeathers
1 March 2008 at 11:26 am
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
Jovan
3 March 2008 at 12:55 pm
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
ffeathers
4 March 2008 at 7:36 am
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
Jovan
4 March 2008 at 5:30 pm
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
Werner
14 March 2008 at 7:03 am
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
ffeathers
14 March 2008 at 10:36 am
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?
Sara
15 April 2008 at 10:46 pm
Hi again Sarah,
do you have any good tips for writing guidelines for technical documentation internally for the developers?
Sara
15 April 2008 at 11:01 pm
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
ffeathers
16 April 2008 at 8:32 am
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
Sara
16 April 2008 at 11:15 pm
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
ffeathers
18 April 2008 at 8:03 am
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.
Shirley
4 June 2008 at 7:40 am
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
ffeathers
4 June 2008 at 7:58 am
I, too, am a tech writer. Please email me privately, as I have a work related question.
Thanks,
Terri
Terri
12 June 2008 at 3:10 am
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
Rupert
6 July 2008 at 7:47 am
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
ffeathers
6 July 2008 at 2:24 pm
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
Garrett Evans
9 July 2008 at 3:30 am
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
ffeathers
9 July 2008 at 8:01 am
Hello,
I’m wondering if I may contact you by email. I’m looking for a rewarding career path and I’m beginning to suspect that technical writing may be well-suited to my personal strengths. However, I need to speak to tech writers and determine how I can best confirm or deny this suspicion. I’m also searching for information on how I can most effectively and cost-efficiently break into this field. Recommendations and dialogue from and with you, or any other tech writers reading this would be welcomed and greatly appreciated.
Thank you!
Sarah
29 September 2008 at 10:40 am
Hallo Sarah
I’d be delighted to give you some pointers. Tech writing is a great career. Please would you add another comment to this page, supplying your email address in the text box when prompted? WordPress won’t publish your email address, but it will send it to me. That way. I can email you privately.
ffeathers
29 September 2008 at 11:10 am
Hi Sarah,
As a Tech Writer, I’ve recently started evaluating and testing Confluence with a view to deploying it within the company in which I work. Currently I’m getting used to it’s features and functions.
A couple of questions have arisen.I wonder if you could answer them please?
1) When building a table, I have assigned all panel specifications to those presented within the Confluence User Guide format. (E.g. Solid blue border etc.) However, unlike the Confluence User Guide, there is an additional border surrounding the coloured border, effectively a greyed out border line. Why does this line appear when it has not been specified within the mark up? Equally, how do you remove it?
2) How do you retain the table settings to ensure they are consistent? I.e. if I add a new graphic or extensive text within a table, it ’stretches’ it, making it look untidy.
Any guidance you could offer would be much appreciated.
David
9 October 2008 at 7:08 pm
Hallo David
It’s great to hear that you’re evaluating Confluence. I hope you’re having fun with it
It’s a bit difficult to help with your questions, without seeing the wiki markup code that you are using. I’m guessing you are using Confluence 2.9, which is the same version as we’re using for the docs.
For the first question: In the Confluence User Guide, we use the “panel” macro to achieve the tables. I’m not sure why you are getting an extra border. I’ve tried to reproduce the problem, but no luck.
Here’s a tip that may help: You can see the markup we’re using on any page in the docs. Go to the “Tools” and select “View Wiki Markup”. You can then also copy the markup code.
For the second question: Tables in the basic Confluence markup or Rich Text Editor will stretch when you add graphics or whatever. There isn’t a way to restrain the width of a column. But you may find some help with a Confluence plugin.
One of the great things about Confluence is that there’s a whole community of developers (both Atlassians and others) writing plugins which extend the basic Confluence functionality. Some of the plugins are officially supported by Atlassian, others are not. Even when they’re not officially supported, you may find them useful and the plugin author should be able to help with advice.
Here’s a link to the home page for the Confluence plugin information:
http://confluence.atlassian.com/display/CONFEXT/Home.
And here’s a specific plugin which you may find useful for table width and other formatting:
http://confluence.atlassian.com/display/CONFEXT/Table+Plugin
In particular, the “table-plus” macro provided by the above plugin may be useful.
Another idea: The Atlassian Pre-Sales engineers would be delighted to help you with your evaluation of Confluence. They have a very good idea of the solutions available for specific problems, and they are keen to help people who are evaluating the product. You can contact them by email at:
sales@atlassian.com
I hope all this helps. It’s great to hear from another wiki-savvy tech writer
ffeathers
10 October 2008 at 7:25 am
Great post about being an Agile tech writer, link being passed around Twitter as we speak. Are you on Twitter also? I’m at http://twitter.com/gerrykirk
Gerry Kirk
9 January 2009 at 2:30 am
Hallo Gerry and thank you very much for the punt on Twitter. Yes I’m there too, at http://twitter.com/SarahMaddox. You have put some useful hints recently on Twitter! I plan to follow your links and have a good read this weekend.
ffeathers
9 January 2009 at 8:19 am
Hi Sarah,
You may recall I submitted a question to your blog last October 9th? Your response addressed the issues I was experiencing. Thank you.
I’m a lot more familiar with Confluence now and after company wide deployment it has been well received by all users.
I am currently developing a Confluence documentation space for the IT Development team in-which I work. They want to have two spaces (Confluence Classic theme and Default theme) linked with one another; the classic space being the parent and the default space, the child. The structure is quite involved, but works and meets everyones needs. However, ideally I’d like to ‘hide’ the default child space from the Dashboard as it will make little sense without it’s associated links to the Classic space. Is it therefore possible to ‘hide’ spaces from the Dashboard to meet this objective?
Regards
David
David
4 March 2009 at 7:26 pm
Hallo again David
That sounds really interesting. It’s great to know that your evaluation project was successful — well done!
I’m afraid I don’t know that much about this area in Confluence, because the core Confluence functionality doesn’t support nested spaces or hiding spaces in the way you’d like. And I focus on documenting the core functionality. An interesting point is that we actually restrict ourselves to the core functionality (very few extra plugins and macros) in our own documentation wiki, so that our customers will be able to download and use the documentation in their own Confluence instances. And because we eat our own dogfood
But that’s an aside.
But it is most probably possible and I know that many customers do wonderful things with the plugins and with customising the templates. Somebody is sure to have done it already. I’d suggest that you try asking a question in the Confluence User Community space on our documentation wiki. For example, here’s a page that may be useful. Otherwise, the discussion forum is a great source of information. You could search it to see if the topic has already come up, and pose the question to see what other people have to say about it now. If you mention the version of Confluence you’re using, and any plugins/macros too, that will help to get useful replies.
Good luck with your IT documentation space — it sounds awesome! When it’s done, it would be great to read a blog post about it
Cheers, Sarah
ffeathers
5 March 2009 at 7:25 am
Many thanks for your detailed response Sarah.
I’ll research the links you’ve provided and post a question on the forum if nothing relative is currently available.
Regards
David
David
5 March 2009 at 6:48 pm