About me
My name is Sarah Maddox. I am an author, blogger, and explorer of the natural world.
Blog: ffeathers (you’re reading it)
A traveller’s blog: Travelling Worm
A bird blog: Birds in Sydney
Instagram: @sarahmaddoxoz
Reddit: u/sarahmaddox
Mastodon: aus.social/@sarahmaddox
X: @SarahMaddox
My books
I’m excited about the books I’ve written:
- Let me introduce you to Trilby Trench, action hero and technical writer. In her own words: I’m Trilby Trench. As in the hat, the coat. The role of a technical writer is more exciting than you’d think. Things happen to Trilby, and she happens right back at ’em. Get A Word if you Please and Words Words Words on Amazon.com, in Kindle and paperback.
- Next up is a romantic drama with a strong psychological theme: Things Unseen. Read more about the book, or grab it immediately from Amazon.com (Kindle).
- Are you one for a quick read, romance with a touch of adventure? Try Daredevil May Care. Read more about the book, or grab it immediately from Amazon.com (Kindle).
- My first book was technical, about developing documentation on a wiki. It’s also about technical communicators. And chocolate. The title is Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. Note: This book is now out of print, though you can download a free PDF version of the book from the publisher, XML Press. .
Intrigued? There’s more detail on the page about my books.
ffeathers 
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
Nice of you to drop in 🙂 I’m missing you guys at Face Technologies, but Oz is a great place to be!
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
Small world 🙂 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.
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 😉
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!
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.
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.
🙂
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 🙂
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
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.
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
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
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
Hi Sarah,
I really appreciate your work. If you are interested in helping us with some book reviews on JavaBooks.org please contact us at office@javabooks.org
Regards,
Laura
Hallo Laura
Wow, that’s an honour. Thank you so much for the invitation. I think that the books at JavaBooks.org may be a bit too Java-oriented for me to do a worthwhile review, so I’ll pass on this one for now.
Cheers,
Sarah
Hi Sarah,
There’s a really cool thing about being a technical author that few ever mention: You get to go to product dev meetings and, with total impunity, ask the same irritating d.fool basic questions (on behalf of your audience, naturally) until something gets done. Just sometimes, you can get folk to see the “elephant in the room”, so to speak.
In your team’s case, PLEASE keep on asking for an offline Confluence client. Smaller enterprises can’t discuss, or even demo. Confluence, without it.
Does Attlasian enjoy condemning potential customers to the really miserable end of SharePoint? They seem like such really great people! 😉
Oh, last but this time seriously, I do hope Atlassian’s management are as impressed by their documentation team’s response to Agile as they should be. Great work.
–Mike
Hallo Mike
He he, condemning people to the miserable end of SharePoint, I like that. I haven’t heard it put quite like that before.
As tech writers we do have input into what goes into Confluence, but alas we are just one small party in a number of interested parties. Confluence is unusual as a software product, in that there are so many use cases and business scenarios for it.
Thank you for your kind words about our technical writing team. It’s a great team and I feel very privileged to be part of it.
I’ll certainly mention the request for an offline client for Confluence whenever the opportunity arises. I see that it’s a popular feature request with many votes: CONF-3726. There’s also a healthy discussion about it on the wiki. Lots of people are interested indeed.
Thanks for an interesting comment!
Cheers,
Sarah
Hi sarah,
I am rajeshwari from India. I am a beginner in technical writing but I am really very much interested in it. As you are one of the top 100 technical writers, I would be glad if you could give me some suggestions, so that I can improve my technical writing skills. I am very enthusiastic and want to achieve great success in this field.
thanks,rajeshwari K S Bhat
Hallo rajeshwari
Welcome to the cool world of technical writing! 🙂 It sounds like you already have one of the most important requirements for the job: passion and the will to succeed.
As far as guidelines go, I think one of the best things you can do is read the blogs and other things that people are writing, about technical writing in particular and also about the field you have chosen. For example, if you’re interested in the IT field, then subscribe to a few of the top news blogs, like CNET technology news or TechCrunch. You don’t need to read everything, but just skim the headlines to see what’s happening and then dive in when you see something you’re interested in.
Have you read Anne Gentle’s book, “Conversation and Community”? It’s a good read, and has lots of interesting ideas about where tech writing may be headed in the future. I wrote a short review. Here’s Anne’s page about the book.
There are basically three parts to tech writing:
1) The writing itself. It may be useful to find a course on structured technical writing, instructional design and/or information mapping. It’s really useful to learn how to structure and categorise information so that other people can absorb it quickly.
2) The thing you’re writing about. A tech writer needs an indepth knowledge of their field. So talk to people and read a lot. Dive in and try out the technology wherever possible, by downloading trial software and installing it.
3) The people. A tech writer needs to talk to a lot of people in the course of their daily job. The best thing is to ensure that you’re well prepared for any meetings, and to know exactly what you need to get out of people.
Well, that’s kind of a whirlwind tour. There’s a lot more, but that will get you started. Good luck and have fun!
Cheers
Sarah
Hey Sara,
Thanks for the response and I am really sorry for the late response. As I was busy hunting for the job could not find time to spend here. I am now working for Accenture. To be frank your words are really inspiring and I will definately read the book “Conversation and Community”? as you suggested.
Thanks so much for the time,
Rajeshwari Bhat
Sarah,
I’m very interested in your work (I’m working to be a technical writer, myself) and would like to maintain communication with you. Would that be okay, and is this blog the best place to do that?
Thank you,
John R Larsen
Sarah,
I’m sorry to include this as a separate message. If you’re interested in seeing my blog, the URL is http://sifm1.wordpress.com/
Thank you,
John R Larsen
Hallo John
It’s nice to hear from you, and especially good to hear from a new tech writer. Thank you for the links to your blog. Yes, I think that the blogs are a great way to keep in touch with each other’s work. There are a number of great tech writers who blog regularly and share ideas and technologies. Try Googling for technical writer blogs. Welcome to the clan!
Cheers
Sarah
I apologize for taking a while to respond. Thank you for your note. I appreciate your taking time to be friendly even though you have thousands of things to do. Sarah, what are a couple major issues you find technical writers currently dealing with?
Thanks and regards,
John
Hallo again John
Heh, well, there are just a few answers 😉 on this thought-provoking post on Tom Johnson’s blog: Guest Post: Tech Writing Careers — The Raw, Unvarnished Truth. Take a look at the comments on that post too.
Cheers
Sarah
Sarah,
Thanks very much. I really appreciate your thoughts and even your links. I had the pleasure of meeting Tom. Would you like to see some of the things he told me in person?
Always a pleasure,
John
P.S.-How difficult is it to find a technical writing career in Australia? I’ve thought on a number of occasions that I’d love to live there.
Sarah,
I’m writing a wiki requirements doc for converting our user docs to a wiki. I want to use Confluence over any other wiki. I’m using http://www.wikimatrix.org as a starting point. A huge requirement is WYSIWYG, and the specific wiki we’ve been offered to use is not WYSIWYG. I’m also getting a little hung up on our scope such as which docs to convert. I think we should start with our user docs and keep our Support’s knowledgebase and Marketing info separate. Do you have any examples of requirements docs you could share? I think this would help lots of tech writers in my position. Thanks!
Gina
Hallo Gina
I don’t have any requirements specs for technical documentation on a wiki. I’ve tweeted the question, because I’m sure I’ve seen some recently but I can’t for the life of me remember where! I hope someone else will drop a comment here, resulting from my tweet.
In the meantime, you may be able to draw some information from my recent article about how we use the wiki for technical documentation. The article covers many of the tasks and requirements for technical documentation. It’s a PDF file, attached to this post:
Cheers
Sarah
Sarah,
Thanks very much for the link to the article. In the meantime, our product manager gave me product requirements and market requirements templates to use, so I’m combining them into one document.
Gina
Sarah,
Are you attending the STC Summit in Dallas May 2-5, 2010? I’ll be presenting three 20-minute “progression” Content Strategy sessions on our experiences with converting our RoboHelp and Flare docs to Confluence.
Gina
Oh, wow, I’d love to be there! Unfortunately, Dallas is a bit of a way from Sydney. 😉 Will you be able to record the session or post any presentation slides after the Summit?
Cheers, Sarah
Sarah,
I think all tech writers in the world should chip in and sponsor you! I hope someone from Atlassian will have an exhibit there. Do you know if they will?
Thanks,
Gina
Hallo Gina,
That’s a good idea! At the moment Atlassian doesn’t have any plans to exhibit or sponsor the summit. I’ve suggested it to our Marketing team. Let’s see what they come up with.
Cheers
Sarah
Hi Sarah,
There are five wiki presentations so far (see the preliminary program at http://www.softconference.com/stc/slist.asp?C=3145
Stewart Mader is presenting one of them: http://www.softconference.com/stc/sessionDetail.asp?SID=182066
And Sun Microsystems is presenting one — and they use Confluence (http://www.softconference.com/stc/sessionDetail.asp?SID=184822)
It would be GREAT to have someone from Atlassian there (especially you) as there is a great interest by technical writers to convert their docs to a wiki.
Thanks!
Gina
Hey Sarah,
I’m a writer just getting started at a start-up company that uses Confluence. I’m the only writer and was hired to build their doc infrastructure. My plan is to use Confluence as the authoring environment and publishing platform. If you’re up for it, I’d like to ask you some questions and get some advice from you about pitfalls I may encounter. Please let me know what you think.
Thanks,
Dan
Hallo Dan
Awesome! I’m sure you’ll love Confluence. 🙂 I’ll email you too personally, and also here are some guidelines to start off with.
Our technical sales team have recently started putting together some material specifically around using Confluence for technical documentation. Here’s a link to their pages. (The content is tailored for people who are evaluating a hosted Confluence instance, but it’s all relevant to you as well and is a good starting point).
http://confluence.atlassian.com/display/CONFHOST/Documentation
I’ve also written a few blog posts over the last couple of years, with hints about how the Atlassian technical writers tackle certain procedures on the wiki. This page has a list of links to the most relevant posts:
http://confluence.atlassian.com/display/DOC/Tips+of+the+Trade#TipsoftheTrade-Usingawikifortechnicaldocumentation
An Atlassian developer has recently created a special theme for documentation, called the “Documentation Theme”. It’s in a very stable state now and I’d definitely recommend it for your documentation spaces. I wrote a blog about it a while ago:
Using a wiki is a great experience for a tech writer — at least, that’s been the way I’ve felt since I started using one about 2 and a half years ago. I hope you have lots of fun too.
Cheers
Sarah
Hi Sarah,
Your website caught our interest because we are looking for technical writers who are users or ex-users of Author-it, MAdCap Flare, Doc-to-Help, Help&Manual or RoboHelp, and who are willing to participate in a survey addressing the user friendliness and experiences of the above mentioned authoring-tools.
We are students of the Raboud University in the Netherlands and have to perform this research for our study. On the following link you can check out our questionnaire (www.thesistools.com/?id=123256).
Please let me know if you can help us find respondents, we would really appreciate it!
Thanks in advance!
Kind regards,
Anne
Hallo there Anne
I’ve completed the questionnaire, and blogged and tweeted about it today. I hope some other technical writers will follow along too. Good luck with the survey!
Cheers
Sarah
Thanks a lot Sarah, we really appreciate it!
Anne
Hi, Sarah,
We’re shifting to Agile and I’ve been reading all the wonderful blog posts you and Ed have posted on the subject.
Is there anything available that describes your typical sprint? I’m still not clear on where/how documentation fits into the Agile model. From everything I’m reading, it seems like we’re a ‘nice to have’.
Many thanks,
Patty Blount
Hallo Patty
There are a few technical writers writing about work in an agile environment.
Mary Connor (Clever Hamster) writes some really great posts. Here’s one: Agile’s natural disciplines. I’d recommend taking a look at her earlier posts too.
Diana at The Agile Technical Writer posts some excellent in-depth information. For example: Sprinting for the Finish Line.
I hope they give you some useful information. I like the idea of a post that describes a typical sprint! Maybe you or I could write one, one day. 🙂
Cheers
Sarah
Hi. I found your blog in the Tech. Writer Blogs directory. As a vendor of help authoring software, we often have different opportunities for bloggers who write on this topic as well as news and special offers that can be of interest to your readers.
Can you please send me an email address that I can use to communicate with you?
Mrs. Maddox,
Hello, my name is Eric Conte and I am a student at Temple University. I am currently taking a business writing course in which we need to interview someone about communication within the career field we hope to find a job in. I have been looking at your blog and was wondering if you would be interested in answering a few questions for me on communication within the technical writing field? I couldn’t find an email contact to reach you at so I figured I would try posting here. Sorry if you have a contact up and I missed it. If you could let me know either way I would greatly appreciate it. Thank you very much for your time.
-Eric Conte
Hallo Eric
Sure, I’ll have a go at answering your questions. I’ll send you an email message.
Cheers
Sarah
Dear Sarah,
I came across you as I was browsing Susan Wu’s post on a day of a technical writer in Shanghai/China. I’m in the process of inviting technical writers across the world to contribute to a story collection I’m working on. This upcoming collection is titled Negotiating International and Cross-Cultural Technical Communication: Stories of Technical Communicators. Unlike traditional academic publications, it invites practicing technical communicators to tell their stories negotiating international and cross-cultural contexts. I noticed that you have worked in many different cultural contexts and would really like to see you contribute a story. I’d be happy to send the detailed call for contributors. Look forward to hearing from you!
Best,
Han Yu, PhD
Assistant Professor
Technical Writing & Professional Communication
English Department
Kansas State University
130, E/CS Building
Manhattan, KS 66506
Hallo Han Yu
Thank you so much for getting in touch with me. I’d love to receive your call for contributors. I’ve replied directly via email.
Cheers, Sarah
Hi Sarah,
We’ve been tinkering with the idea of moving our documentation to Confluence. As a starting point we have been evaluating it and it’s awesome.
From what I gather, the documentation at Atlassian is done directly on Confluence itself – am I correct? If I am, how do you go about the usual cycle of documentation reviews (esp. Peer and SME reviews)? or it is non-existent in a way that the SME’s and Peers directly make the changes to a Confluence page and add comments for that page?
OR
The documentation is done in say, MS Word with the usual documentation cycle followed (with SME and peer reviews done in MS Word, for example) and the “final and ready to be shipped” document is finally imported from MS Word to Confluence.
Would be really thankful if you could share how you folks go about the documentation cycle at Atlassian.
The folks at Atlassian are the most transparent when it comes to sharing their processes, hence I didn’t hesitate to ask you directly. I could have contacted your sales team on this but I wanted to hear it from a technical writer at Atlassian. 🙂
Thanks!
Hallo Jimmy
It’s nice to hear from you, and it’s great that you’re enjoying Confluence!
Yes, you’re correct in assuming that we write the documentation directly in Confluence. The entire workflow happens on the wiki. Answering your specific question about drafting and reviews, here’s how we do it:
I wrote an article a while ago, which you may find useful. It’s a PDF file attached to this blog post:
In the same blog post, you’ll find a link to some PowerPoint slides which have better screenshots.
You may also find some useful links here:
http://confluence.atlassian.com/display/DOC/Tips+of+the+Trade
I wish you lots of wiki fun. 🙂
Cheers, Sarah
Wow, that was quick. You folks at Atlassian truly rock!
“When ready, delete the comments and remove the permission restrictions. The page is now ‘published’, because it is visible to the world (based on the wiki and space permissions, of course).”
You made me go through the “Why didn’t I think of that!” moments when I read the above. 🙂
Thanks so much!
Hi Sarah
I’ve been peaking at your blog for some time now as the company I work for is considering moving our product documentation to a wiki. I’m a lone writer and the entire process is foreign to me. Do you have any suggestions on where I should begin?
Thanks
Hallo Gala
Oh, you’re in for a lot of fun! I mean that seriously, not sarcastically. Since I moved to a wiki I’ve never regretted the move or missed the tools I’ve used in previous jobs. 🙂
Anne Gentle has a great post that lists a number of technical documentation wiki sites. They might be useful to you, for giving some ideas of what people are doing with wikis:
Here’s a link to an article that I wrote, which you may find useful for getting started with the process of managing technical documentation on a wiki. The article focuses on Confluence wiki, because that’s the one I use. The article is a PDF file, attached to this blog post:
The above article is based on an earlier presentation I gave. You may find the slides of that presentation useful, because the screenshots are easier to see than those in the PDF file:
To get started, I’d suggest that you download a wiki and play with it. 🙂 It’s surprisingly easy to install and play with Confluence. You can run it quite easily on your laptop. Or you can try it out in the online “sandbox”, which is open to anyone and everyone. Here’s the link to download your own wiki or try it online:
http://www.atlassian.com/software/confluence/try.jsp
If you decide to download Confluence, you can have a free evaluation licence for 30 days. It’s also free forever, for non-profit and open source organisations. Otherwise, you can pay $10 for a 10-user licence (proceeds go to “Room to Read”). Commercial licences are based on number of users.
If you go for the evaluation licence, then the Atlassian pre-sales engineers are delighted to help you with specific questions around using Confluence for tech docs. You’ll also receive some useful links to tech doc use cases and so on.
I hope all this info helps, and above all I hope you have lots of fun!
Thanks so much for the guidance!
Hey Sarah,
thanks a lot for your blog, which opens a wide window on the tech writing craft.
As many of the commentators of this page, I am asking myself the question: Wiki or not Wiki for the whole documentation?
A response I’ve had from tech writing experts is that, I quote, “[Wikis] are designed as all-in-one systems: writing, revising (and tracking revisions), organizing (cross-linking), and presentation/delivery all within the same tool. They are *not* designed to facilitate authoring of information that will be delivered outisde of the wiki itself, because that externally delivered information is (by definition) a static snapshot rather than the living, evolving body of knowledge that is the wiki ideal.”
So, as I’ve understood, the ideal would be that tech writers and developers maintain a wiki for internal use, and tech writers use another tool to produce documents for external use (pdf, EclipseHelp, online help, etc.). And that both content be exchangeable.
In your specific case, do you produce content in your Wiki that you then export for external use? If yes, in which format?
Thank you very much!
Mathieu.
Hallo Mathieu
That’s a very interesting question, and one that more and more people are asking as they start integrating a wiki into the other systems they and their customers use.
At Atlassian, we do export the wiki content for external use. We provide it in PDF and HTML format. We also provide an XML file, which people can use to re-create the documentation space on their own Confluence site. We produce the exports as a snapshot at the time of each major release.
Confluence has built-in tools for producing PDF, HTML and Confluence-specific XML exports. There are also add-ons for more tailored exports.
I’ve written a blog post on the subject quite recently, and also a new guide that you may find helpful.
Here’s the blog post: http://blogs.atlassian.com/confluence/2010/11/technical-writing-wiki-single-source-publishing.html
Here’s the guide, which is part of a guide to developing technical documentation on Confluence.
PDF: http://confluence.atlassian.com/display/DOC/Providing+PDF+Versions+of+your+Technical+Documentation
Other formats: http://confluence.atlassian.com/display/DOC/Exporting+and+Printing+Technical+Documentation
I hope that helps. 🙂
Cheers
Sarah
Hi Sarah:
I am a writer and I consult with a company that has conducted one FedEx Day and is planning to have more. Did Atlassian invent FedEx Days? I’ve found several sources on the web that credit you with the invention. I’m writing a background story on the event and would like to verify this fact if possible.
Thanks,
Lee
Hallo Lee
Yes, Atlassian invented FedEx days. Here’s the original blog post by one of our two CEOs, Mike Cannon-Brookes, announcing “The Inaugural FedEx Day” in 2005:
http://blogs.atlassian.com/rebelutionary/archives/000495.html
Things have changed since then, of course. 🙂
Have fun with your story. I’d be interested to read it when published, if you’d like to post a link.
Cheers
Sarah
Hello Sarah,
My name is Bellavy Ros and I’m an upper division student at San Francisco State University majoring in Technical and Professional Writing. I perused your blog and have found very informative advice that you have given others. For our graduation requirement, we have to interview a subject matter expert for our white paper on a specific technology that technical writers use in their workplace, and the effect on their profession. Would it be possible if I emailed you questions regarding Confluence and the direction it’s moving for experienced technical writers, like you? I understand that you are busy and I greatly appreciate you taking the time to even read this.
I hope to hear from you either way, and I thank you for your time.
-Bellavy
Hallo Bellavy,
That sounds like an interesting white paper. I’ll have a go at answering your
questions. I’ll email you. 🙂
Cheers, Sarah
Hi Sarah,
Would like to discuss Tech Doc process you use at Atlassian. How you use Confluence for collaborative writing etc. for developer-facing docs.
Thanks!
-Brad
Hallo Brad
I’d be delighted to discuss this with you. 🙂 I’ve emailed you personally.
Cheers, Sarah
Hi Sarah,
My company has used Confluence internally for several years, and now we are about to make some troubleshooting and “how to” pages available to customers in the form or a technical knowledge base. My concern, as a tech writer and user advocate, is how to make it easy for customers to find the pages they need. The pages are not organized in a parent-child format, and as there are currently about 400, it would be a major project to do that now.
From what I’ve read on the Atlassian site, labels can increase search ranking, so I’ve started to come up with a list of keywords, and I was thinking I could apply those to pages as the site grows. I’m assuming that that would increase the probability of pages appearing in search results if users didn’t happen to type in a term that’s used in a page title or content.
Am I on the right track here, or are there better ways to improve searchability? I’ve read the label pages in the Atlassian documentation, but I can’t find any that address using labels for searching, so I’d appreciate any advice.
We’re using Confluence 3.5.6.
Thanks!
Lisa
Hallo Lisa
Labels are a good way to go. They will improve searchability, both via the Confluence search and for Google searches. Another thing you can do, once the labels are in place, is to create a page with a set of “content by label” macros. That is one way of offering people a categorised list of pages.
Another option is to offer people a link to the space’s “Labels” view, which shows all the labels in the space. People can click through to see the pages for each label. To see an example, click the “index” link in the left hand column of any of the Atlassian doc spaces.
I hope this is useful. 🙂
Cheers
Sarah
Thanks, Sarah. I like the idea of a link to the Labels view in the left column.
Hi Sarah,
I really enjoy following your blog, it’s a good inspiration for my work as technical writer,
I would very much appreciate your thoughts on the following scenario:
We do use confluence and are right now working on a complete and current version of an online documentation (it’s not public yet). And moreover use confluence for internal purposes like future research, administrational information etc.
We are right now thinking about whether it would be best to create a 2nd instance of confluence for the public documentation inside a separate web space to make absolutely sure that no costumer will be able to see any other internal space (e.g. the space about future research, administration, etc.).
I know there is the possibility to address certain permissions and views for specific users (or e.g. for visitors that are not authorized users). But will this be 100% bulletproof?
Would the separation be too cumbersome? How do you operate with this issue?
Thanks for your thoughts & Kind regards
Chris
Hallo Chris
My advice would be to have a separate instance for the public documentation. This would be better for security reasons, as you have already suggested. It also makes sense because the audience and purpose of the two sets of content are different. When people are writing content on the internal site, they are aware that they can say anything, express any opinion and use any style. When they are writing on the external site, they are aware that the content is destined for public consumption.
At Atlassian, we have an internal Confluence site that we use as our intranet. It has company news, HR policies, fun and games, plans, rants, anything under the sun! We also have the external Confluence site that holds our documentation and discussion spaces where customers can have their say. This site is also open to anonymous viewers.
Let me know when you documentation wiki goes live. Exciting. 🙂
Cheers, Sarah
Thanks for the quick reply,
That’s very interesting to hear.
I assume that you you guys do the whole documentation release management in the seperate instance as well. And do not work inside the internal space on all the documentation updates and then export to the public instance on release day. Right?
Kind regards
Chris
Hallo Chris
Actually, we do work in the current space. We just use page restrictions to hide all our updates from the general public until release day. It’s rather a manual process, and we’re working on automating bits of it. I’ll write about it when we eventually get a better process going!
An alternative solution is to use the Ad Hoc Workflows plugin (https://plugins.atlassian.com/plugin/details/142) to control the workflow and publishing process.
Cheers, Sarah
HI Sarah
I’ve been following your blog since we got Confluence and Jira at work, and am hoping you can steer me to some help.
We use FrameMaker for all our user documentation. We ship PDFs and CHM with our software products. I’ve been asked to investigate the potential of replacing the PDFS and CHM with Confluence.
I’ve worked with Confluence 3.3.1 to create pages ( I like the wiki markup editor) so I’m sold on it as a vehicle for users, but how do i get my FrameMaker 9 files up to Confluence without a lot of labour intensive adjusting?
I’ve put pages of FrameMaker text content to HTML and then into Confluence. But the bulk of my documentation is in FrameMaker books and in a two column, graphics-rich format . How do convert a whole book (or at least a whole chapter) into Confluence, so it divides the source into many pages instead of one long one?
Another issue is that some of others here want to continue to use FrameMaker as the documentation manager, which i think would involve having to update the Framemaker files from changes made in Confluence and vice versa, which would essentially be two sources that could go their separate ways…not good.
Your suggestions for directions to search for answers to these questions and any advice would be gratefully appreciated.
Susan in Canada
Hallo Susan
Thanks for dropping by, and for following my blog! And I’m glad that you like Confluence. 🙂
I’d recommend that you keep just one platform, either Confluence or FrameMaker, as the primary authoring tool. I don’t think there’s a tool available that will allow full “round tripping”, in other words converting from FrameMaker to Confluence and back again while merging the changes made on either platform.
There is a good solution for people who would like to continue using FrameMaker as the primary authoring platform. WebWorks ePublisher converts content from Adobe FrameMaker to Confluence. WebWorks ePublisher provides a sophisticated set of standalone tools for converting your Word documents to Confluence. You can design templates to define the styles and format of your output documents. Best of all, you can automate the conversion via batch processing and scheduling. I wrote a blog post about it a while back. There have been a few releases of ePublisher since then, but the post and the comments on the post are still interesting and give a good overview: https://ffeathers.wordpress.com/2009/10/04/epublisher-for-converting-documents-to-confluence-wiki/
Once the content is on the wiki, you could use the Confluence space permissions to prevent people from editing the pages that are sourced from FrameMaker. You could allow people to view and add comments to the pages in those spaces. Other spaces could allow people to add and update pages, as well as add comments. In this way, the wiki could still be a place for community contributions as well as offering the official documentation.
Let me know what you decide. It sounds like a very interesting project.
Cheers, Sarah
Hi Sarah,
I read just your post in the Atlassian blog (Technical Writing in a Wiki – Single Source Publishing) from last November and it has been really useful as I am currently researching into the feasibility of implementing DITA with Confluence. One of the things that we are specifically looking into is how to export content from Confluence into DITA, as the goal is to make the wiki the central authoring and repository tool. So I was wondering what happened to the Confluence-DITA plugin that K15t was going to launch? And do you know of any other tools that would allow this type of export?
Many thanks in advance for your response
PS. I tried to post this comment at Attlasian, but I wasn’t able! I am new to Confluence and I recently started my post as techwriter (although I had some previous experience).
Ximena
Hallo Ximena
It’s great to hear you’re about to start working on Confluence. I hope you enjoy it! I have not heard any more from the K15t guys about the DITA export plugin. I’ll ping them and see if they have any news. Have you considered using DocBook instead of DITA? I know that the K15t team have just released the latest version of the Scroll Wiki DocBook Exporter plugin, with many improvements.
Happy wiki writing. 🙂
Cheers
Sarah
Hi Ximena,
DITA is still on our list. However, the issue with DITA is that the DITA topic types mandate some kind of structure on the content. So the question is how do you want to enforce that structure in the content?
Of course we could leave it to the user to make sure the content structure is correct, and fall back to convert a confluence page to a generic ‘topic’, however we feel that this would not be user-friendly enough.
Therefore we have postponed the DITA export and have worked on Scroll Wiki Forms, which allows to enforce content structure within a wiki page. We have made a EAP version available and a shot demo video can be found here: http://www.k15t.com/display/en/Scroll-Wiki-Forms-for-Confluence-Overview .
So, after Scroll Wiki Forms has reached 1.0-final we will start looking into DITA export for Confluence. If you have any comments about DITA support for Confluence, feel free to email me stefan [at] k15t (dot) com. We are interested in your ideas!
-Stefan
(K15t Software)
Hi Sarah and Stephan,
Thank you very much for your quick reply. First, to answer Sarah’s question we are looking into DocBook as well. Some brief background, I just started my post as techwriter last week. So I am currently familiarizing with the company’s documentation procedures and needs. I have been charged with researching the possibility of implementing DITA within our process. We are using Confluence, mainly for collaboration and storing docs, yet the wiki is not used to its full potential yet. One thing we need to do to start is to update to the 4.0 version. I was specifically asked to research if it is possible to convert docs in Confluence to a DITA xml format, using a plugin. So, now I know this is not yet possible. Tomorrow we’ll have a meeting and I will present the findings. I believe though that the first task should be to assess our requirements and documentation needs, as maybe it will turn out that we do not really need DITA. We could work with Docbook or maybe directly in Confluence and the Scroll Wiki Forms. I did some research on XML authoring tools in my previous job as techwriter, but I have not had the experience of working directly with such tools yet or with structured content. And that is the case with my team mates as well. But they all are very excited with DITA. Well, thanks a lot again for your feedback and I will keep you posted with news.
Greetings from Bolivia
Ximena
Hallo again Ximena and Stefan
This is a very interesting conversation. I agree that we need some sort of structure on Confluence pages, when exporting them to DITA. It wouldn’t be very useful to export plain topics, without any typing. That would nullify the strong points of DITA in most cases, I think. The use of Scroll Wiki Forms combined with a new Scroll Wiki DITA Exporter sounds ideal.
Thanks for offering to keep me posted, Ximena. I would love to know how things turn out!
Cheers, Sarah
Sarah, Would you be willing to talk to me about working at Atlassian? I’m a US dev and writer who’s been working in rural Queensland and is looking for a change. I have a very strong technical background (ie, I’m not one of those writers who does grammar edits on a UX spec, revises the screen shots and calls that a user guide… I’ve actually been a hardcore C/C++ dev for years). When I worked at Microsoft a friend who’d been at the company for a decade called me “the geekiest woman I’ve ever met, and I mean that as a compliment”. Our link is only 3rd degree, so I could not connect to you on LinkedIn.
Hallo Helen,
Yes, I’ll talk to you with pleasure. I’ll send you an email message when I get to my desktop tomorrow morning. 🙂
Cheers, Sarah
Hi Sarah,
I just read that you’ll be presenting at the STC Summit in Chicago in May, 2012! I cannot wait to meet you and to see your presentation on wikis. I also am anxious to purchase your book. I’m struggling with how to translate our wiki without breaking the plugins.
Gina
Hallo Gina
It will be great to meet you at last! Also, I’m keen to hear about your requirements and progress in translating content. As I’ve mentioned before, I don’t have any experience in that field. Atlassian does not see it as a priority for our own documentation yet, so I have not had a chance to start planning and designing for translation and localization of our content. I’d love to hear what you’re doing, and the problems you’ve encountered. With the ability to export to DocBook, PDF and Word, we should have most translators covered. But I guess the sweet spot lies in optimising the processes.
See you in Chicago. 🙂
Cheers, Sarah
Sarah,
Thank you for the quick response. We need to translate our user documentation from English to French, German, Portuguese, and Spanish. We tested exporting the wiki content as xml and Word docs to our localization service provider. Our LSP compares the source language with our translation memory, translatea the files, then we re-import it to the wiki. Exporting the xml won’t work because there was not a way to exclude the page history. We just want to translate the official current content — not the comments or history. Exporting to Word didn’t work because that stripped out all of the plugins. Exporting the wiki markup was the only other option, because it doesn’t contain the page history, but the page title is not included by default so we have to manually insert it before sending it for translations. This is also a lot of manual work because we have to keep track of which files (topics) have changed, manually export and send the wiki markup per file, then re-import the translations into the separate translated spaces (we have each language in a separate “space”). I had looked at the Bitvoodoo plugin, but that keeps the translations in the same space, which we don’t want to do. And we’d have the same problems mentioned above, anyway.
Some component content management systems include translation management. It might be that you’d have to manage the wiki through the CMS, which is expensive to purchase until you eventually achieve ROI on translation costs. It seems like someone could come up with a plugin so that we could export the xml files from Confluence that we want to translate, which would include some kind of markup with “do not translate” on anything that does not need translating or that would break the re-import (such as plugins and page history).
See you in Chicago.
Gina
Hallo Gina
Ah, I see, it’s importing the content back into the wiki that’s the main stumbling block. As it happens, one of the Confluence developers is currently improving the XML export, and is adding an option to include/exclude the page history. (There’s already an option to exclude the comments.) I don’t know when the change will go live. Keep an eye on the release notes. 🙂
What do you do about screenshots — do you get a translated version of those too?
Cheers, Sarah
Hi Sarah,
That’s great! An option to exclude the page history (as well as the comments, which I had forgotten can already be done) would certainly help. So by exporting and importing the xml file, the plugins shouldn’t break as they did with the Word export/import. It would really be helpful for someone at Atlassian to explain which part of the xml file is the the current content so that the LSP can set up the Trados (or other translation software) to read the file and only translate what’s necessary (new and changed content).
We typically don’t use screenshots. If we do, we normally run our software in the specific language and use SnagIt to create the screenshots ourselves. It’s much easier than asking the LSP to learn our software and take the time to create them. Of course, we have to wait for the application strings to be translated and get them into our build before we can create the translated screenshots.
Gina
Hallo Gina
I’ve put together a post resulting from recent discussions with you and a couple of other people: https://ffeathers.wordpress.com/2012/02/05/translating-documentation-developed-on-confluence-wiki/
In particular, I’d love to know what you think about the idea of using the Copy Space plugin to exclude page history.
Cheers,
Sarah
Hi Sarah,
I liked your blog. It is full of knowledge-base resource for technical communicator community. I would like to place your blog link in my site.
I hope it is okay with you.
Regards,
Harjot
Hi Sarah,
I’ve ordered your book some days ago but got a message that my order has been canceled.
Can you tell me why and when it is possible to order the book?
Regards
Rolf
Hallo Rolf
There are some problems with the Barnes & Noble page for the book. The publisher is investigating that issue, and I’ve let him know about your message too. I’m so sorry about the confusion. I’ll let you know as soon as I hear more.
Thanks for letting me know about the problem. I hope it is sorted out quickly.
Cheers
Sarah
Hi Rolf,
I’m sorry about the troubles with Barnes and Noble. I’ve been working with them to figure out what the problem is, but don’t have a definitive response, yet.
However, if they can’t complete the order, we will work out a way for you to get the book.
I apologize for the problem, and as soon as I have a response, I’ll post a reply here.
Richard Hamilton
Publisher, XML Press
The new look is cool! 🙂 What’s the story behind switching?
Thanks Shweta! I loved the Journalist theme that I was using before, but it didn’t have the tabs across the top showing pages. When I added the new page with details of my book, I wanted the tabs so that people could find the “my book” page easily. So I looked around and found this great theme.
Cheers, Sarah
Hey Sarah,
I am an Italian Blogger. I would like if you put a translator on your web page so that it can be easier for me.
Thanks
Rubel
Hallo Rubel
Unfortunately, I can’t add a translator on WordPress.com. I’m using the hosted site, and the translation plugin is not available. Have you tried Google Translate, at http://translate.google.com?
Cheers, Sarah
Hey Sarah,
Thanks for answering me. Yeah I used to use Google Translate, however, it is not always useful. Anyway, I will keep tring use it.
Rubel
Hi Sarah,
we noticed that the copy space plugin seems to be working with Confluence version 4.2. Does this sound familiar? Do you knwow if there is anyone still developing upgrades for this plugin (since it is not regulary supported by Atlassian).
Since this plugin is really a core feature for tech comm, we are very eager to find a solution.
Thanks very much for your help.
Best regards from Germany
Chris
meant to say it does *not* work with 4.2 🙂 in our case
Hallo Chris
We’re using the Copy Space plugin with Confluence 4.2, and it seems to be working. I agree it’s an essential plugin for tech comm. 🙂 I’ll email you privately, to find out what problem it is giving on your site.
Cheers, Sarah
Hi Sarah, since you are an expert Confluence user, perhaps you can help me with this.
Here’s the issue as I wrote it originally. (You can see the whole case at https://support.atlassian.com/browse/CSP-79415?page=com.atlassian.jira.plugin.system.issuetabpanels:all-tabpanel ]
)
One-liner: How do I make links relative?
When I say “relative” I mean that the link points to a page in the current space, but automatically updates to the analogous page when I move the page from the current space to a different one.
Here is the detailed story:
I maintain two spaces, one for development, one for the public. They are typically more or less exact duplicates of each other. That is, if there is a page in the dev space, there is usually an analogous page in the public space.
I typically edit a page in the development space, then copy it to the public space.
When I copy the page (go to edit view, select the entire page, control-c, go to public space, control-v), the links do not update correctly. They do not update at all, that is the problem.
Let’s say I am working on a page called ME in the dev space and I use “advanced” to create the link to a page called YOU. I don’t get any choice as to which space I am linking to. Confluence just assumes that I am linking to YOU in the dev space.
Then I copy ME to the public space. I want the link to update itself to point to the YOU in the public space. But it doesn’t. It points to YOU in the dev space. It does not update at all.
Is there a way to create the link in the ME page in the development page so that, when I copy it to the public space, it points to YOU in the public space?
I realize that I can use “Search” to hard-code the link to the public space, but that isn’t a good long-term solution. In a few months, I will deprecate the current public space and make the current dev space the public space. I can’t have links pointing to the deprecated space.
Sarah, is there a way to get the behavior that I want? The tech support guys (Rodrigo, Luis, Guilhereme) said they consulted with Atlassian’s techncial writers (maybe even you!) but the reply they sent back did not help me.
Hallo Susan
It may be that you’ve run into a bug we encountered with relative links in the early Confluence 4.x versions. I’ll take a look at your support ticket for the full story. (If the support ticket doesn’t say which version of Confluence you’re using, please would you add that to the ticket?)
To create relative links in Confluence, you can use the “search” or “previously viewed” tab in the link dialog. Alternatively, you can enter wiki markup (i.e. just the page name) in the “advanced” tab of the link dialog. I’ll need to test the scenario you’ve mentioned, which I’ll do after checking the support ticket.
Cheers, Sarah
Hallo again Susan
I’ve investigated the problem fully, and encountered the same problem as you. Confluence doesn’t respect relative links when you copy the content of a page via the editor, if you are copying from one space to another.
The good news is that there is a workaround. It hinges on 2 facts: (1) The page copy function (“Tools” > “Copy”) does respect relative links. (2) When you copy the content of a page within a space, using Ctrl+C and Ctrl+V, Confluence does leave the links as relative.
So, the workaround is:
* Use the Confluence “Tools” > “Copy” to copy the page to the new space. Let’s assume your page is called “X”. When you copy it, it will be named “Copy of X”.
* If the page did not yet exist in the 2nd space before you copied it, just rename the page from “Copy of X” to “X”.
* If the page “X” already exists in the 2nd space, edit “Copy of X”, select all the content, Ctrl+C to copy it. Then edit “X” and paste the content into it. Confluence will respect the relative links in this case.
I’ve raised an issue for the development team to consider, and I’ve added more details there too: https://jira.atlassian.com/browse/CONF-25366
Cheers
Sarah
Hi Sarah
We are confluence users and Crowd users, and since you wrote the OpenID section I was wonding if the OpenID can look up Windows Integrated Authentication to assess whether the user is logged in rather than having to login to windows and then login to Crowd. Seems obvious, so wondering if you have suggestions of where to look.
Danel
Hallo Daniel
Thanks for dropping in. 🙂 I don’t know the answer to your question, but I’ll ask some experts and either I or someone else will reply as soon as possible.
Cheers, Sarah
Hallo again Daniel
I have the answer from our gurus. Crowd doesn’t support Windows Integrated Authentication. There’s some information in this issue: https://jira.atlassian.com/browse/CWD-760
Sorry it’s not a yes, but at least it’s a definite answer. 🙂
Cheers
Sarah
Thanks so much for tracking that down.
I think we will write a plugin to enable Crowd to check the Integrated Authentication in addition to the traditional login – Do you think there would be interest in this, I see that others do want the feature.
Hallo Daniel
That’s an interesting idea. You could add a comment to the CWD-760 issue, and also add a question on the Atlassian Answers site:
http://answers.atlassian.com
People may come up with interesting ideas as well as saying whether they’d use such a plugin.
Cheers
Sarah
Hi Sarah,
i have a question. We use both a local installation of Confluence as Intranet and a on demand Confluence solution to let our users access our online documentation. Therefore, we heavily depend on the Copy Space Plugin. Since we export our most current version of online documentation as XML and Export into On Demand.
So far so good.
Thing is: Requirement for the import in On Demand is that you exported from a confluence with the same release number.
I made a technical test for our autumn documentation release and thereby On Demand refused to allow the import of my XML since On Demand is now at release 5.0.
did i miss something?
Since when is Confluence 5.0 released. I do not find information on that on Atlassians website. Can we even already update our local installation to 5.0.
I’m a bit confused by that. Did you hear anything about this issue, Do they use the On Demand Accounts for pre-tests of new versions.
Thanks for your help
Chris
Hallo Chris
I’m sorry that this is causing you some trouble. I’ll see if I can answer your questions and clarify what’s happening.
Before I start, there’s one point in your question that I’d like to confirm my understanding of: You mentioned that you heavily depend on the Copy Space plugin. Am I right in assuming this means that you use the Copy Space plugin on the Intranet, to do version control for your documentation? In other words, that’s why you need to have the source of the documentation on the Intranet (where you can install plugins) and the customer-ready version in OnDemand (where you can’t install the Copy Space plugin).
Now, to answer your questions.
Yes, it’s true that Confluence OnDemand is now running Confluence 5.0. Atlassian’s policy is to release new features into Confluence OnDemand regularly, and in advance of the Confluence downloadable versions that people install for themselves. So at any one point in time, there’s a good chance that Confluence OnDemand will be a major version ahead of the downloadable version of Confluence.
In answer to this question: “Can we even already update our local installation to 5.0.” The short answer is, Yes.
But before you go any further, it may be worth consulting the Atlassian support team (http://support.atlassian.com) about your special case. They may be able to help you, by doing the space import into OnDemand for you even though the Confluence version numbers are different. If you do decide to consult support, please feel free to refer to this comment. It may give the support engineer some more understanding of your situation.
Now, on to what I know.
There is a special downloadable version of the Confluence OnDemand release (currently version ‘5.0-OD-1’), made available especially for people who need to export content from OnDemand to an installed site. The instructions for installing this ‘OD’ version are here:
https://confluence.atlassian.com/display/DOC/Migrating+from+Confluence+OnDemand+to+a+Confluence+Installed+Site
The above page also includes important information about the limitations and support of the ‘OD’ versions.
Now, your case is different, because you want to export from an existing installed site (your Intranet), and import it into OnDemand. As far as I can see, this means that you would need to upgrade your Intranet site to the special ‘OD’ version (currently version ‘5.0-OD-1’) so that you can export the data and import it into OnDemand. In other words, you will need to follow only steps 2 and 3 on this page: https://confluence.atlassian.com/display/DOC/Migrating+from+Confluence+OnDemand+to+a+Confluence+Installed+Site
* Start at step 2.
* When installing the ‘OD’ version in step 3, use it to upgrade your existing Intranet instead of just doing a clean installation of a new site.
* Skip steps 1, and skip steps 4 to 6.
Alternatively, you can download and install the special ‘OD’ version into a temporary new site, then export the entire content of your Intranet site to an XML backup, and then import that XML backup into your new ‘OD’ version. This will work, because the full site backup and restore does not require that the sites have the same version number. Then you can export the required space from the ‘OD’ version, and import it into your OnDemand site.
Another complication is that you need to do this regularly, not just once. The ‘OD’ version will be different next time you need to do it. For example, it may be 5.0-OD-2 or 5.0-OD-3, or whatever. So you will need to download and install a new ‘OD’ site each time you want to update the documentation.
That’s a bit onerous. 🙂 So I suggest that you try contacting the support team in case they have a better idea.
Good luck with this, and if you’d like to let me know how it turns out, I’d like to hear that.
Hi Sarah,
and again thanks for your quick and sharp help.
I’ve started to talkt to the support via JIRA (link to issue https://support.atlassian.com/browse/JST-45007 )
That is for me the important part of the reply:
—
“One option that you might consider is installing another 4.2 Confluence instance and import the spaces there, and upgrade that instance to 5.0 early access program, then from there you can obtain a compatible exports to Confluence OnDemand.
I know that this is not a very handy workaround as it involves manual work. But we are discussing this internally with our developers on how to ease the process of importing/exporting between different versions of applications in OnDemand and BTF.”
—
Sounds like your suggestion, but i agree, that is “extremly onerous”.I can’t expand our (already time consuming) publication workflow in such a high degree. This is simply not working for us.
So, I would much more prefer if they would agree to your other thought: “They may be able to help you, by doing the space import into OnDemand for you even though the Confluence version numbers are different.”
But they answered me: “If I obtain your XML file I won’t be able to directly integrate it to your OnDemand Confluence.”
In the momentary sitution this brings up the question if we can continue working with the on demand solution of confluence.
Hope the support will be able to help with a more convenient solution.
I’ll keep my fingers crossed.
Many Thanks
Chris
We use copy space for version control and for cleaning the history of changes, since we do not necessarily want our customers to see every step in the creation of our documentation.
I have so far not seen any other way to clean the page history in confluence. Or is there any other?
Hallo Chris
Thanks for letting me know the results, and linking to the issue. I’ve had a look at the response from the support team, which is that they can’t do the import easily either. I’ve also raises this matter with the product managers directly, so that they are aware of it. Unfortunately, that won’t help you with your immediate problem. If the support team can’t think of another solution, then it seems to be insoluble.
I hope you find a solution that suits you. Let me know if there’s any help I can give you.
You’re right about the way you use the Copy Space plugin. There’s no other way I know of that cleans up the version history. Another interesting plugin is Scroll Versions, which does sophisticated version control and lets you publish your content to the same space or a new space. It’s pretty cool. It’s a commercial plugin, and is unfortunately not available in OnDemand: https://marketplace.atlassian.com/plugins/com.k15t.scroll.scroll-versions
Cheers, Sarah
Hi Sarah, I am reading Confluence, Tech Comm and Chocolate (or should I say, eating it up). I use MadCap Flare and it works very well as a HAT for online help and pdf. I really enjoy using it and the new html5 format has been appreciated by our technical group (they can help users search help easily with links to topics exposed).
I also produce a separate set of docs that are not provided as online help. These are written by subject matter experts and require formatting and editing by me. And we go back and forth many times. It’s a real pain in Flare to have multiple writers and editors who are not using Flare. There is a tool called Contributor but it doesn’t allow round tripping and the contributors must understand Flare anyway, need training and publishing still must go through Flare.
This set of docs is a perfect test case for a wiki, and luckily, the engineers in my group picked Confluence for their internal communication tool, so it’s available to me as well.
What I am sad to see is that MadCap Flare is not noted as an import option in your list in the chapter on importing and exporting content. I am sure that if I look hard enough, I will figure it out, but I wondered if you had a starting point for me.
My assumption was that I could import html files, and use my style sheet, but I am getting the idea that the proprietory nature of the some of the code will make this very hard. It looks like I’d have to export to Dita xml and then import to Confluence.
Hallo Linda
You’re right, I think the best option is to export from Flare to DITA, and then import to Confluence. The DITA2Confluence tool currently works on Confluence 3.x, but there are comments in this thread from someone who has successfully adapted it to use the Confluence 4.x API:
http://sourceforge.net/projects/dita2wiki/forums/forum/864448/topic/4988108
It’s a shame that the options for importing content into Confluence are as limited as they are. 🙂
Cheers, Sarah
Hi Sarah,
Thank you very much for such a quick response. I am having success with exporting from Flare to Word , tweaking the styles in Word (to be able to split topics into pages by headings) and then importing the Word files to Confluence with very little trouble.
The major issue (for a few hours) was trying to figure out how to get the images. The images were showing up in Word, but not on the import to Confluence. There is a setting in Flare in the Word target to embed images, so I tried that and it worked perfectly.
I will explore the DITA option, but as I am completely unfamiliar with DITA and more or less familiar with Word, I might carry on with Flare to Word to Confluence, although I haven’t yet figured out what I might gain if I used DITA. Would I retain variables and snippets, for example, and how?
I am a real newbie to wiki, not very technical at all, and finding this fun and addictive.
My plan is to complete the project as much as possible in Flare, using all the functionality I am familiar with and then continue in Confluence and not go back to Flare with this particular project.
One thing I wonder about is why I cannot edit the CSS for a space as space admin, and must be the sys admin to do that. The sys admin doesn’t want to micro manage, and that seems too bad.
Thanks again, this is one product where I am very happy with the quality of the documentation and learning from it, instead of giving up and rewriting the documentation for our users based on my experience with a third party product!
Linda
Hallo Linda
It’s awesome that you’re able to export from Flare to Word and then import the docs into Confluence. I’d thought that that process would be too time-consuming, since you can only import a single Word doc at a time. But if Flare can bundle up a number of topics into a single Word doc and you can then split them again via the Confluence import, that is great!
I don’t think you would gain much from a DITA import, especially since you’re only planning to do the import once rather than on a regular basis. Also, the DITA import may be tricky since you’d need to get hold of that update that makes it compatible with Confluence 4.
Yes, it’s a pity you need to be a sys admin in order to edit the CSS for a space. The reason the developers give is that CSS is pretty powerful, and could open the Confluence site to security attacks if someone inadvertently adds insecure CSS.
I’m so delighted that you’re finding the documentation useful! There’s a lot we want to do, to keep improving it.
And on that subject: Your experiences would make an excellent blog post! In particular the tip about setting Flare to embed the images in the Word docs. Are you planning to write a post about it? If you don’t have access to a blog, I’d be delighted to publish a guest post by you.
Thanks for an interesting comment chain.
Cheers, Sarah
Linda, are you exporting from Confluence to MadCap Flare? I might need to export Confluence pages to a HAT, would be interested in your experience. TIA.
Very interesting TIA. I wonder why you are doing that?
I like to lead a pretty uncomplicated life, so I think my projects will remain discrete, for the time being.
The projects I am turning into Context Sensitive Help will stay in Flare, the ones where SMEs do most of the content work and the output doesn’t need to be CSH and users need to access easily will move to Confluence. I have the luxury of both tools right now.
I also recall that there is a plug in or a plug in is coming to create CSH from Confluence, so I am interested in that.
I really love working in Flare, and appreciate all that it does. It’s super fun for me.
Check out the Flare forums, if you are using Flare, as I think others (maybe you!) are doing the same thing. I still don’t know why.
Linda
Hi Sarah,
It’s going to be a slower process than I would have liked, due to competing deadlines but I am documenting my process and would be delighted to share my experience with your readers.
It’s been great to be able to post here and not feel so alone, it gives me validation as a writer who is passionate about wikis as a documentation tool. I have great support from engineering and product management, I couldn’t do it without them.
Linda
Hallo Linda
Awesome! Let me know when you’re ready to blog about it.
Cheers, Sarah
Hi Sarah,
did you already experience how well copy space runs with the new Conflunece 5.0? I once had trouble to use it after a release upgrade. And I don’t want to step into the same trap door again. Thanks for any feedback Chris
Hallo Chris
We tested the Copy Space plugin on our Quality Assurance site before we upgraded our Production site to Confluence 5.0. The plugin passed the tests, performed by two tech writers in our team. I haven’t tried it in production yet, but the QA site is a copy of Production, so it should be fine.
Cheers, Sarah
Hello Sarah, I am wondering about your experience with allowing users to comment on Confluence help pages.
Since you continue to allow commenting, you must think it a good thing. How have comments helped you (as a writer) or users (as users of Confluence)?
Do you moderate comments before they are posted?
Have you had to remove offensive comments?
Is there an automatic way to delete comments after a certain time period?
Many thanks!
Hallo there stregasmom
Whether to allow comments is a hot and oft-debated topic here in the office. As a writer, I find the contact with people’s day-to-day problems and concerns is an eye-opener. I’d say that it’s changed the way I approach writing and refactoring documents. For the customers, direct contact with a technical writer, product manager or support person on a document page gives valuable context — they don’t need to describe the entire problem, because the context of the page brings everyone in line.
On the other hand, it’s often impractical to answer everyone’s comment. We have buttons and links at the bottom of every page, pointing to forums and other resources, but still there are people who get upset (and justifiably so) when their comment isn’t answered.
Often another customer will answer someone’s question. That’s great.
Yes, we do sometimes have to remove offensive or unhelpful comments, or spam.
There isn’t a way to remove comments, or archive them, after a certain period. We keep promising ourselves that we’ll build such an add-on, but time and priorities haven’t allowed it yet.
I hope this helps. 🙂
Cheers, Sarah
Sarah – have you seen the recent thread on the Framers mailing list?
Here’s a snippet:
Confluence 4’s import path is supposed to be MS Word, but there are
several bugs that make it unusable: cross-references are broken,
numbers are converted to plain text instead of ordered lists, and each
node of the TOC is sorted alphabetically.
I think Atlassian is in a catch-22 as regards the tech docs market:
they don’t fix those bugs or support bulk import because not enough of
their users are voting for those bugs or enhancements, and not enough
users vote for those because it’s too hard to migrate legacy content,
so tech docs departments are not using Confluence.
Your take on any of this?
Hallo Jeff
Thanks very much for this interesting discussion point.
The Confluence product managers are looking at improving the importers at this very moment. They’re not considering the Word importer in isolation, but rather the whole picture: how to make it easier to get content into Confluence from other sources including other wikis. I’ve suggested one route would be to pick a single, common format and make a superb experience for that format. Then people could export from their existing source into that format, and import into Confluence with confidence that it would work. One such format could be HTML. (It’s currently possible to import a single HTML page, but not a hierarchy or an integrated site.) Another format could be a recognised XML format such as DocBook or DITA.
The number of votes on an issue or request does play a good part in determining the features the Confluence team focuses on. But it’s also true that the general, strategic direction of the product plays a big part too. Typically, a release will have a particular focus and then the issues will be cherry-picked. For the last few releases, the focus has been on general collaboration rather the tech docs. There’s now a focus on features that are of interest to larger enterprises too. That bodes well for tech docs, because often the two areas overlap.
I’ll pass on your input to the Confluence product managers. I hope I’ve helped to answer some of the questions.
Cheers, Sarah
Hi Sarah,
Not sure if this where to ask about this, but: can you think of any reasons I wouldn’t use one instance of COD to develop tech doco and then another instance to publish it for customers. So one instance would be our internal site with draft versions etc and the other instance would contain the signed-off doco and be accessible to customers?
The reason we are thinking of doing this is to simplify the whole permissions things:) Do you know of anyone else who has done this? pros? cons?
Thanks Lillia.
Hallo Lillia
It’s a reasonable choice. The only con I can see is the complexity of transferring the content from one site to the other. Are you planning to use the XML export/import process? In that case, you’ll need to make sure the versions of both sites are compatible. At the moment, that means both sites must be running the same “major” version of Confluence. For example, both must be on 5.1.x, or both on 5.0.x, or both on 4.3.x.
An alternative is to use the Confluence CLI (an add-on developed by Bob Swift) to copy the page content across. That involves a fair bit of manual configuration.
I’ve heard people debating this question, but I don’t know of anyone specifically who is doing it at the moment. A good place to ask is on the forum:
http://answers.atlassian.com
Cheers
Sarah
For Lilia, who asked about having both development and public versions of Confluence doc:
We do this at Echo360. My thoughts:
1 – Sarah’s caveat about copying a space is well considered. We use the Copy Space plugin but it is a little temperamental.
2 – We learned to keep the development space (with access restrictions) and the public space (without access restrictions) on the SAME server. This is very important.
3 – Text created with the multi-excerpt plugin does not copy automatically but there’s a quick fix.
4 – I use one color scheme (with a big red band on the top of each page) for the development space and a different one for the public space. I often have the same page open in two different tabs, the different color schemes tell me which space I am in.
HTH.
Hi stregasmom,
Thanks for that, nice to know someone else is doing this and it’s not completely crazy thought! One of our big issues is we use Confluence on Demand not Confluence so we cannot use the copy plugin:(
I do like your colour scheme idea though:) and will use that.
Thanks.
Lillia.
Hi Sarah
I have taking a look to an article you published: https://developer.atlassian.com/display/DOCS/Checking+Plugins+for+API+Compatibility
I had some problems to try some plugins with this tool (https://answers.atlassian.com/questions/172346/checking-plugins-for-api-compatibility) and I was wondering if you could tell me more info about how is this tool made, if may be is the source code available? or the creator of this tool to ask him/her about the problem?
Thank you
Best Regards
Leonardo Onieva
Hallo Leonardo
I’ve forwarded your request to the developer who created the plugin checker. I hope he’ll get back to you soon. In the meantime, it’s great that you posted the question on the Atlassian Answers – that’s a great forum for getting help.
Cheers
Sarah
yes you’re right. Thank you sooo much 😉
cheers
Leo
Hi, Sarah!
I work in a technical publications department and I have an interest in the qualitative analysis of documents such as product briefs, data sheets, application notes, user’s manuals, and programmer’s guides. The plan is to benchmark our documents against leaders in the industry. I would like to know if you have any metrics (or know of anyone who does) that would be helpful in compiling and analyzing documentation.
Thanks in advance.
Take care,
Greg
Hallo Greg
I’m afraid I don’t have anything useful. I’ll tweet the question, with a link back to this page, and hope others have some information for you.
Cheers
Sarah
Hi, Greg, how would you want to measure quality?
“Developing Quality Technical Information” by Gretchen Hargis, et al. has several useful criteria for what makes for high-quality documents, such as task-oriented, accurate, complete, clear, concrete, well organized/structured, retrievable, visually effective. However, most of these criteria cannot be quantified easily and most cannot be automated reliably. They usually require one or several human judges which makes the whole benchmarking process quite costly.
For a more extensive discussion and resources, see my blog post http://kaiweber.wordpress.com/2011/02/14/improve-documentation-with-quality-metrics/
JoAnn Hackos publishes benchmarking metrics See http://www.infomanagementcenter.com/
Hi Sarah!
I am a follower of your blogg and found it very interesting and useful in my tech writer daily tasks. Thanks for that! Though, I have a question regarding Google Docs (as you are a tech writer and working at Google I think you are the one to answer this:-)). We are using both Google Docs and MSWord for producing documents in my company. This is a bit tricky. For Word we have a bunch of nice templates to use but what ever I do I cannot get any format to work out for Google Docs for providing templates within this. Google Docs, as I have read in threads on internet, does not fully support the open document format (.odt) and as I have realized too destroys the format when open it up in Google Docs view. And get back and force between Google format and Word-format is not an option since it destroys the format even more…
Do you use Google Docs and templates? Do you have any suggestions of how to do this for working out properly? I think it is hard to use Google Docs if we do not have a common look of the documents for providing version number, headings, listbullets etc.
Thanks!
/Lena
Hallo Lena
Thanks for your nice words about my blog. I’m glad it’s given some help and ideas. Regarding the question about Google Docs and Microsoft Word: I don’t use either of those for technical documentation at the moment, so I’m not the best person to answer the question. I see that you’ve been looking at the forums already, so you may have already tried the Google Docs group. It’s probably the best place to get answers and find out what other people are doing with the product:
http://productforums.google.com/forum/#!forum/docs
Cheers
Sarah
Oki, I will check the product forum to see what to do about the formatting issues etc in Google Docs.
Though, I am a bit curious about how you handle the documentation in your daily work. 🙂 What tools do you use and how do you store the documents and ensure them to be properly version handled? Does it work out well? What do you recommend to use for a company of a size of 150 persons spread world wide?
Thanks!
Hallo Lena
We use an internally-developed tool set at Google. The tool you might choose for your company depends on a number of requirements. I’d recommend that you make a list of requirements (such as version control, review and approval workflow, multiple authors, permission scheme, security, user contributions and/or feedback, output formats, and so on) based on what you and your stakeholders need. Then assess a few different types of tools and match their capabilities up to your requirements: wikis, help authoring tools, CMSes, Office, and so on.
Cheers
Sarah
Hi Sarah, I have just been reading your blog which I thought it was really interesting! I’m based in NZ and I currently work as a Quality Administrator for a food manufacturer where I maintain and update manuals and SOP’s. I deal with these daily and I am at that stage where I feel ‘stuck-in-a-rut” and I feel I could do further so I am looking to get into Technical Writing. I have recently attended various Adobe courses (paid by the company) and found them really good and motivating. Also, I am hoping to get into the Information Mapping 3-day workshop next month (and my employer won’t pay for it, bummer) so the more I learn and obtaining skills, the better! Hopefully I will land a dream job as a Technical Writer one day soon! If you have any useful tips, let me know! Thanks, Claire
Hallo Claire
It’s good to hear you’re interested in technical writing. It’s a great job! Adobe training and Information Mapping make for an excellent start.
Getting a job as a tech writer is all about experience, unless you can come in at graduate level. So it’s excellent that you already have some experience that you can cite, as part of your current role.
Another idea is to take on a few jobs editing existing documents, or doing a short contract for someone who’s looking for a writer on short notice. I’ve seen jobs advertised on this mailing list for two- or three-week roles, either editing or writing:
http://www.techwr-l.com/archives/1301/index.html#.Ukei0D-39Bw
http://www.techwr-l.com/frequently-asked-questions.html#subscribe
An excellent resource for you in New Zealand is TCANZ:
http://www.tcanz.org.nz/
They’re great people and do lots of work in the training sphere too. If you can find some meetings of tech writers in your area, the contacts you make there will be very useful. 🙂
Good luck!
Cheers
Sarah
hi Sarah! I didn’t realize you left Atlassian. Congrats on going to Google! I read your book “Confluence, Tech Comm, and Chocolate” – very good, very helpful! I’m trying to use Confluence but finding issues importing MS Word docs that have steps/numbering – the import tends to make them all 1s and changes the indenting formatting. Any ideas how I can get this to work? We have loads of Word docs that need imported but they have many levels of numbering/indents.
Hallo Mary Jo
There have been problems off and on, with lists in imported Word documents. The solution/answer will probably depend on the version of Confluence you’re using. One tactic is to look at bug reports on the Atlassian issue tracker. Here’s a search to start you off:
https://jira.atlassian.com/browse/CONF-24310?jql=project%20%3D%20CONF%20AND%20text%20~%20%22word%20import%20lists%22
You can see which issues match your problem, and then check to see if they’ve been resolved, and in which version of Confluence the fix was shipped. You can also check out the comments on the issues. If you get a login ID, you can add your own comments to the issues, or log an issue yourself.
Another option is to ask the community at Atlassian Answers. They’re very helpful in knowing the current state of affairs and offering advice:
http://answers.atlassian.com
Thanks for the congrats. 🙂 It’s a big move for me. I’m having fun and learning a lot!
Cheers
Sarah
Hi Sarah,
Let me introduce me first.
I am Naveen from India. I am working as Sr Technical Writer for a product development company. I have gone through most of your blogs and i hear more about Confluence and Wiki. What are these tools all about? Are those the Help Authoring Tools which can be used for developing the Online Help.
Can you please elaborate me on this?
Thank you.
Naveen.
Hi Sarah,
Is there a book you would recommend for the entry-level technical writer?
I saw your blog after searching “google technical writer.” I applied for a position this week but I don’t expect to get it because I lack experience with API documentation.
Thanks,
Matt
matthewlockewong@gmail.com
Hallo Matt
I’ve heard good things about this book, though I haven’t read it myself:
I also think reading blogs and other information on the Internet is a good way to go. And you’re obviously doing that. 🙂
Good luck with your application to Google! Is the role based in Australia or the US?
Cheers
Sarah
Cool, I’ll take a gander! San Bruno, CA USA
Hi,
I’ve just moved to Sydney:) In Poland I worked as a BA.
Looking for information on the technical documentation I came across your blog which I find really interesting.
I am not sure is it a good place but I would like ask you for a favor.
I am going to send my resume to Atlassian for the technical writer position. It is required to send them the sample documentation.Could you take a look on my blog?
I would by greateful for any tips.
cheers,
Kate
Hallo Kate
Welcome to Sydney! The best people to help with an application for a role at Atlassian are the Atlassian recruitment team. If you submit an application for the role, they’ll get back to you to discuss it. I think it’s a great idea of yours, to put your sample docs online. One tip I’d have is to check carefully for typos in the guides.
Good luck with you application, and enjoy this bright clear weather we’re having. 🙂
Cheers
Sarah
Hi,
I will perform a double check:)
thanks,
kz
Hi!
I’m Cailyn, I am a junior in high school and I would like to get a head start on figuring out my future career. Technical writing has always been appealing to me as a possible job but sadly I don’t really know too much about it. Could you possibly give me some insight as to what the job entails, what kind of courses should I take to prepare for this type of job, and what are the most enjoyable parts of the job? Thank you so much for taking the time to read this, I really appreciate it. Love your blog and enjoyed perusing through it.
Thanks again,
Cailyn
Hallo Cailyn
Technical writing is a very enjoyable career, full of challenges and rewards. There’s a fairly wide range of tech writing roles. The first thing to consider is the area you’d like to work in: there are tech writers in various industries including computer software, computer hardware, the medical industry, defence, and more.
Looking at the software industry, tech writers can specialise in API and developer-product documentation, which is focused on creating help material for software developers. Alternatively, tech writers can specialise in end-user facing documentation, such as online help, user manuals, help on mobile devices, and more.
To see the variety of tech writers and the things we talk about, a good place is Technical Writing World:
http://technicalwritingworld.com/
You can sign up for an account there, if you like, and take part in the discussions. People will be delighted to hear you’re considering tech writing as a career.
As far as education is concerned, it would be excellent to have a qualification in the industry you’d like to write for. So, assuming you’re targeting the software industry, then a qualification in computer science would be excellent, with additional courses in technical communication. Assuming you’ll be writing in English, then an English language course would be great too.
In addition, there are technical writing organisations that offer specific courses of varying lengths. For example, take a look at the STC’s education page:
http://stc.org/education
I hope this gives you something to get started with! Welcome to the world of technical communication. 🙂
Cheers
Sarah
Hiya Sarah,
Thank you so much for your prompt response! I’ve been exploring the websites you listed and I’m more excited about my future than I have ever been before. Your information has helped me immensely.
With much thanks,
Cailyn
Been looking for a while for a specialized tech writer/blog concerning wording/usage of digital electronics terms. Pretty specific and boring unless you write computer chip manuals for a living (and love working with words!) Questions like:
“Set bit to 1” or “set bit to logic 1” or “set bit to logic one” or “set bit high” or just “set bit”?
or
“These bits select the sink current of the IRTX pin” or “This register configures the sink current” or “If one were to anthropomorphize an otherwise lifeless heterogeneous crystalline lattice, the arrangement of electrical charges could be interpreted as an electromagnetic manifestation of the “will” of a “superior being,” exerting divine influence on a electromagnetic force vastly beyond the comprehension of anything other than its omniscient self, for the purposes of spreading its infrared gospel throughout the universe.”
Or something like that (perhaps without the theological imaginings).
I’m sure there are other people writing tech documents about things on a digital b/t level, who have already discussed such heady topics.
Kevin Self,
self_kevin@charter.net
Hallo Kevin
Ha, what a great comment! The odd heterogeneous crystalline lattice could do with a touch of philosophical glamour. I’ll tweet a link to your comment, to see if any digital bit writers are feeling theologically imaginative today.
Cheers
Sarah
Sarah, can you have an include macro within an expand macro? I have a page called “Search” that has all the information about searching within the system. I want to have a link that says “View how to search” and when the user clicks it, I want the “Search” page to display. I haven’t been able to find a way to make this work so maybe it’s not even possible?
Paul Hanson
prhmusic at hotmail dot com
Found my answer. Yes, you can include a page within an expand macro! Yeah!! Here’s the wiki markup:
{expand:This is my message}
{include:Search}
{expand}
All I had to do was insert an Expand macro and then specify an Include macro with the name of the page (Search) that I wanted. Too easy.
Paul
Hello Sarah, I met you at the Sydney API documentation presentation for tech writers. My company is adopting Confluence for an intranet site, and I will move my wiki based software user documentation into Confluence. I have noticed your comments on the Atlassian web refer to using a htaccess file to manage context sensitivity. Can you advise who at Atlassian I should contact to get more information? Or should I just go to support and log a request? Regards, John Murphy
Hallo John 🙂
In case you haven’t seen it, this post may have the information you need about the .htaccess file: Using a wiki for online help. If that doesn’t cover it, you could try posting a question on Atlassian Answers. There’s a really good group of users and experts who contribute on that forum. Otherwise yes, a support request may be a good idea.
Cheers
Sarah
Thank You. I would like to thank Google for allowing you to address an Atlassian issue.
Dear Sarah,
I do love your workout about tech comm. And i would like to use in my project which i face some problems to make replacements. Could you pls help me how should revert it to my needs in same temples? Especially spreadsheets.
Sarah, we met at the AODC conference in Darwin some years ago. I’m just stopping by to thank you for your excellent work documenting Confluence! Your book, “Confluence, Tech Comm, Chocolate” answered nearly all the questions we had about issues like version control, archiving, variables, etc, as we made the move from our old print-publishing software to Confluence. And it was a fun read too!
Hallo Suchi
It was so great meeting you at that conference. I remember your presentation well, with the origami and the DITA wolf. 🙂 Thanks for your nice words about the book. I’m so glad it was useful!
Cheers
Sarah
Hi Sarah!
My software company (located in San Jose, CA) is looking to hire an experienced technical writer for a full-time position, and I was wondering if you had any advice for me. Since I have been acting as our interim technical writer I have a good idea of what we’re looking for; the trouble I’m having is actually finding quality candidates for the position.
We’ve already posted on a number of different standard sites, but it occurred to me that you might know of some folks looking for a full-time position and/or some job boards or forums where I could post the job posting/solicit a more targeted audience. Any guidance you could provide me during this process would be much appreciated.
Thanks so much!
Lauren
Hallo Lauren
From personal experience, LinkedIn is a good way of putting technical writers in touch with jobs. There’s the standard LinkedIn job search. Also, you could have a look at the technical-writing focused groups to see if any of them fit the specialist category you’re looking for.
Another good place to published a targeted post is Technical Writing World.
If you like, I can tweet about your comment, with the tag #techcomm, pointing to this page, and see if any good things result from that too. Let me know.
Cheers
Sarah
Hi Sarah,
Thank you so much for your speedy and thoughtful response! Per your advice, I just added a job posting to the Technical Writing World job board: http://tww.jobthread.com/job/senior-technical-writer-san-jose-ca-zl-technologies-b64c5811fa/9ddedc77010fdb73bfc9cec65eb500e9/?d=1&source=site_apply_done&excluded_view=1. I would be very grateful if you could tweet about my comment and/or the job posting.
Again, thank you for your help! I’ve followed your blog for awhile now and have been consistently impressed by how insightful and thorough your posts are, so thank you for that as well.
Warmly,
Lauren
Hallo Lauren
That looks like a great role. I’ve tweeted about it here: https://twitter.com/sarahmaddox/status/571035521935212544
Good luck to you and to prospective candidates for the role!
Cheers
Sarah
I was wondering if you could answer some questions for me. If you could answer them by midnight on Sunday, I’d be very appreciative. This is for my Technical Writing Class.
1. What kind of writing do you do daily? Weekly? Yearly?
2.Did any of your courses in college prepare you for writing?
3. Who reads most of your writing?
What kind of impact does your writing have on your job?
4.How often does your writing go through revisions?
5. How did you learn to write for your job?
6. What happens when you write well? When you write poorly?
Please email me your answers as soon as possible. This is very important
Hallo Matthew
Sorry, I can’t respond to a request like this, at short notice and especially over the Easter break. I do have a couple of suggestions for you to try. One is to post your questions on Technical Writing World. Another is to create an online form, such as a Google Form or a Survey Monkey form, and then ask for participants via various social media. For example, on Twitter you could use the hash tag #techcomm to reach the right people.
Cheers
Sarah
Hi, Sarah, my name is Matthew Kahne. I was wondering if you could answer some question that I have. This is for my technical writing course, and I kind of need them by Sunday. Please email me your answers at makahne@sbcglobal.net your earliest convenience. Thank you for your time
1. What kind of writing do you do daily? Weekly? Yearly?
2.Did any of your courses in college prepare you for writing?
3. Who reads most of your writing?
What kind of impact does your writing have on your job?
4.How often does your writing go through revisions?
5. How did you learn to write for your job?
6. What happens when you write well? When you write poorly?
Sarah,
Thanks for your post about API writing. I’m on the East Coast and would love to purchase your workbooks as I’m unable to travel to attend your workshops.
Are there any plans for remote access to your classes? I’d love to attend one if you have any planned.
I always enjoy reading your blogs!
Hallo Bobbi
Thanks so much for asking about this. At the moment, the workbooks are only available to the people who attend the workshop, but I plan to make all the material (lectures/slides as well as workbooks) publicly available as soon as I have the time to convert them to a suitable format. They would then be free of charge. It’s on my list of things to do. 🙂 Please stay tuned to this blog for updates.
Cheers
Sarah
Thank you so much Sarah. I look forward to seeing the workbooks!
Hi Sarah! I have an interesting technical writing consulting opportunity opportunity that I think your passion and expertise would be a great match for. I work for Smarterer, a Pluralsight assessment company, and our technical writing skill test could use some love. If you’re interested, can you shoot me a note? I’d love to chat about what we’re thinking. Thank you!
Hallo Bhavika
Thanks very much for thinking of me with respect to this opportunity. I’ll decline with thanks, because I’m fully and happily employed with my day job.
Cheers
Sarah
Hi Sarah – totally understand! Thanks for getting back to me.
However, just so you know this would be a limited scope opportunity – 10 to 15 hours of time so if you’re intrigued at all, let me know! Happy to tell you more about it.
Hi Sarah,
I am a fresher who works for Tata Consultancy Services, I have been given the role of a technical writer and we use Adobe Frame Maker for writing documents. I just wanted to know what are the different tools used in Google for technical writing. I will be delighted if you could also tell me the pay structure for a technical writer in Google.
Hallo RamyaSindhu
There are many technical writing teams at Google, and different teams tend to use different tools. In my area, we write the documentation in HTML or Markdown, and can use the editor of our choice. We have a proprietary content management tool that publishes the pages to our site: Google Developers.
Similarly, the pay structure varies for the different teams. If you’re interested in a role at Google, take a look at the technical writing roles advertised and submit your CV for consideration. When a Google recruiter contacts you, that’s a good time to ask questions about salary and other terms.
Cheers
Sarah
Sarah,
I’m looking for a conference to attend this year- something that emphasizes technical communications and/or help site development. What was the conference you spoke at a few years ago? Thanks!
Hallo Linda
There are a number of good conferences, depending where in the world you’re located. I’ve spoken at the STC Summit a few times, as well as the ASTC and tekom/tcworld.
Here’s a good place to find out what’s happening in various areas of the world: Tech Comm on a Map. To find out more about that project, check out the project web page. You can even add items to the map, if you know of something in your area that’s not yet on the map – see the form linked on the above web page.
Cheers
Sarah
Thanks so much, Sarah!
Hi Sarah,
The company that I intern for is interested in single-source publishing via a wiki, but we’re not sure if it’s the right CMS for us. May I email you some questions privately so we can talk about our needs, and if a wiki like Confluence is a good fit? You can reach me at thomas.c.wood@colorado.edu
Thanks!
Hallo Thomas
It’s been a while since I’ve worked on Confluence, so I’m not the best contact for this question. The Atlassian technical sales folks are pretty good at giving guidance. You can contact them at sales@atlassian.com. Another good source of information is the forum at answers.atlassian.com, where you’ll find enthusiastic people from the community as well as from Atlassian.
HTH!
Cheers
Sarah
Hi Sarah,
Greetings, hope you are doing great!.
I am Karthik, working in SAP Labs India as an Information Developer/Technical Writer for about a year.
I have recently heard about you from my colleagues, who had attended your lecture during TC World India, Bangalore 2016. And also, they explained the lecture you had given on that particular day. Glad that I understand the importance of technical communication in the fast technological world.
Basically, I did my graduation in Mechanical Engineering and do not have a strong English. I would like to seek your advice to have a strong written and verbal communication skills and ways to enhance the same.
I do my piece of learning every day by reading books and brushing the contents on and off, but I feel that there is a definite improvement needed with respect to my writing skills. Hence, requesting your piece of advice.
Thanks for understanding,
Regards,
Karthik
Hello,
I may have my 1st technical writer job. The organization wants to set up a collaboration tool that can be easily accessed from mobile devices. The manufacturing company teied Google Docs but didn’t like accessing spreadsheets on the phone.
They are looking to start their documentation process. Do you know how I can look for tools that would work for them?
Thanks
I really enjoyed “Confluence, Tech Comm, Chocolate” 🙂 Even though the Confluence described in the book is quite different from the version we know today, I learnt a lot – thanks!
Hallo Dorte
Thanks for letting me know. I’m so glad you enjoyed the book and found it useful. 🙂
Cheers
Sarah
Pingback: Top 10 Posts for 2009, at Content for a Convergent World « Technical and Marketing Communication: Content for a Convergent World
Pingback: Students requesting participants for survey of authoring tools « ffeathers — a technical writer’s blog
Pingback: Inside the book – Things Unseen by Sarah Maddox | Travelling Worm
Pingback: Agile Marketing At Atlassian (A Brilliant Piece of Content Marketing) - writersgarret.com