Blog Archives
Want an XML schema viewer in Confluence wiki?
You got it. 
Avisi have developed two nifty macros to display an XML schema (XSD) in tabular and graphic format on a Confluence page. The XSD Viewer is a new add-on for Confluence wiki, and the Avisi developers are keen for input from technical writers and others interested in XML schemas.
I’ve been playing around with the add-on, so I’d love to show you a couple of examples and tell you how to get it working for yourself. I’ve also chatted with Yanne from Avisi, who says that he and his team would love to have your feedback.
Example 1: A purchase order schema
I’ve grabbed the sample schema for a purchase order from MSDN: http://msdn.microsoft.com/en-us/library/ms256129.aspx. I’ve instructed the XSD viewer to start with the purchaseOrder element, and show a depth of 2 levels.
Example 2: Graham Hannington’s schema for the Confluence storage format
Hehe, if you put Confluence and XSD in the same blog post, then ‘twould be remiss not to include Graham’s XML schema for the Confluence storage format. 
The XSD Viewer is using confluence.xsd, starting with the image element.
One point of interest here is that the confluence.xsd file references two other schema files: confluence-ri.xsd and confluence-xhtml.xsd. All I had to do to make this work, was to attach all three XSD files to the page. This screenshot shows the attachments on the above page:
Hiccups
A couple of times, the XSD Viewer has declined to show any rows in the table. I’m not sure why this occurs. If it happens to you too, it’s worth letting the Avisi team know.
My environment
I’m using Confluence 5.0.1, with version 1.1.1 of the XSD Viewer. I’m running Confluence on my Windows 7 laptop, and I’m using Chrome to view the wiki pages.
How to get your own XSD viewer
To make this happen, you need to do the following:
- Download and install Confluence, if you don’t already have it. You can try it for free for 30 days. See the Confluence download page.
- Download the XSD Viewer add-on and install it into Confluence. The add-on is also available for free for 30 days. See the XSD Viewer page on the Atlassian Marketplace.
- Create a page in Confluence.
- Attach your XSD file to the Confluence page, just as you would attach a screenshot or other file. See the documentation on adding attachments.
- Edit the page.
- Add the “XSD Image” and/or the “XSD Table” macros to the page. See the documentation for the XSD Viewer.
- Save the page.
Resources
Useful links:
- The XSD Viewer page on the Atlassian Marketplace.
- The documentation for the XSD Viewer.
- A getting-started video for the XSD Viewer on YouTube.
- The issue tracker for the XSD Viewer.
Feedback so far
I’ve given Yanne at Avisi some feedback already:
- At first the error messages were a bit too generic to be useful. Avisi have already followed up on this in the latest version of the add-on, which gives more specific error messages. Great!
- Currently the macro autocomplete in Confluence is triggered by “XSD”. Suggestion: Add “schema” and “XML” to the list of triggers.
- Add the option to add a border and other styling to the image.
The Avisi team like the latter two suggestions, and are waiting for more feedback before implementing them. Would you be interested in an XSD viewer in Confluence, and what requirements would you have for it?
Report from voice and tone seminar by Kate Kiefer Lee
Early last Friday morning (5:30am, to be precise) I attended a webinar presented by Kate Kiefer Lee (@katekiefer) on creating a voice and tone for your organisation. The presentation is titled “Voice and Tone: Creating Content for Humans”. Kate is Editor and Content Strategist at MailChimp.
With this post my aim is to whet your appetite for attending Kate’s session, if you get the chance.
Introduction by Kate
This is what we’re aiming for, when thinking about the voice and tone of our organisation:
- A tone that stays pretty much the same over time.
- A voice that changes all the time.
At MailChimp, Kate deals with plenty of different types of content: email, website, blogs, text in the app… It can seem overwhelming to think about making all those consistent.
The way to tackle it is to find the company’s voice. Our customers are people, just like us. They deserve our thoughtfulness and our respect. The right tone of voice can turn a frustrated customer into a loyal fan.
Finding your company’s voice
Where there’s a company, there’s already a voice. Sometimes you have to dig to find it. Start by asking questions. Talk to the founders and other key people in the company.
These are some questions to ask:
- What does your company do?
- Why did you start your company?
- Why do people visit your website?
- Who are your customers?
- What other companies do you admire?
- If your brand were a person, how would you describe him or her?
This one is Kate’s favourite:
How do you want people to feel when they visit your website?
There’s no need to spend too much extra time to ask these questions. You can slide them in when doing stakeholder interviews.
This is a key thing to note: You’re looking for emotional responses. You don’t want the technical or business response. You want those moments when people’s eyes light up.
Making a list of character traits for your organisation
A list of word oppositions is a useful tool. That’s a list with the structure “x but not y”. Adding the “not” part is really important.
This is MailChimp’s list:
MailChimp is
fun but not childish.
clever but not silly.
powerful but not complicated.
smart but not stodgy.
cool but not alienating.
informal but not sloppy.
helpful but not overbearing.
expert but not bossy.
This list of characteristics is the best place to start any voice and tone guide, and should be right at the front of the guide.
Personas
Personas are a valuable part of the voice and tone content. You’ll probably find that your designers, UX professionals or product managers work with personas. Those personas should be used right across the company.
Other things to include in the voice and tone guide
Kate walked us through a list of things to include in the voice guidelines:
- company’s mission
- content types
- specific content examples
- brand traits
- personality explanation
- reader/customer types
- visual guidelines
Traditional style guides
There is definitely a place for the more traditional writing style guides. But the voice and tone guides are perhaps more suited to being a part of every organisation, and are a little more meaningful. Why?
- There are existing, industry-wide style guides that we can use. We don’t need to write our own entire guide. Instead, we can defer to an existing one and add our own custom items.
- We can edit for style and grammar. It’s really hard to edit for voice and tone, because those are at the heart of and form the very fibre of our content.
Kate gave the example of two writers. Let’s call them Bob and Jack. Bob is an excellent writer but isn’t too good at getting the voice and tone right. Jack is a bit of a sloppy writer, but is right on the button with the voice and tone. Kate finds it much easier to integrate Jack’s content. It’s basically a cleanup job. Whereas editing Bob’s copy isn’t possible. Kate would have to rewrite the content.
Speaking onto the page
Read your work out loud. This stops you from sounding like a robot. It makes you more empathetic, because it puts you into a conversation. When talking to someone, you want to make them feel good and make sure you answer their questions.
Another trick is to read the work as if you’re talking to someone you know. Think of a specific person. This helps you to communicate in a friendly way, and a way that people will understand.
Watching your tone
Voice and tone are different. Tone changes all the time, depending on the situation and the audience.
To help define what “tone” is, Kate showed a picture of her dog. The dog responds all the time to tone of voice. For example, “walk” versus “no”. He responds to the way we say those words, rather than their meaning.
Kate talked about how the MailChimp voice and tone guide evolved. She showed a section of the style guide called “content types”. She realised there’s a huge range of content types. For example:
- There’s humour in the app. But it’s outside the main purpose of the app. You can even turn the jokes off.
- On the other end of the spectrum, there are compliance alerts. This is an example of bad news that you’re delivering to customers. This kind of thing can really ruin someone’s day.
So the customers are dealing with a huge range of emotion when they’re dealing with the content. One tone doesn’t fit all, because that’s not being respectful to the customers.
Determining your tone:
- Consider the content type. Sometimes it’s really simple, such as a joke.
- Think about the reader’s emotional state. This is an exercise in basic empathy. How does the reader feel when she gets to this page, and how will she feel when she has read this content?
Kate listed a set of content types that require a specific tone. For example:
- Financial content, health and medicine, fundraising. This type of content is sensitive.
- Help content. People are usually trouble-shooting when they come here. Not a good place for jokes or marketing.
- Forms are stressful and often involve private information.
- Failure messages and alerts often deliver bad news.
Kate showed us a wheel of emotion, and how she mapped the content types and types of readers to the various emotions.
Types of readers:
- Troubleshooters – people looking for a solution to a problem. Frustrated. Want a quick fix.
- Explorers – people trying to find out about MailChimp. Excited and interested. The content can be more relaxed.
Examples of voice and tone guides
We took a look at some examples of good, effective voice and tone guides from various organisations. I’ve picked my two favourites here.
VoiceAndTone.com
Kate walked us through some parts of MailChimp’s voice and tone guide: http://voiceandtone.com.
Looking at the section on Freddie’s jokes: http://voiceandtone.com/freddies-jokes, we saw that the guide includes:
- A couple of tips. For example, it explains that the jokes aren’t meant to contain information.
- A list of the reader’s likely feelings at this point.
- An example of the content – in this case, a joke.
At the other end of the spectrum is the compliance alert: http://voiceandtone.com/compliance-alert. The guide predicts the reader will be feeling stress, confusion, anger, fear at this point of time. With those feelings in mind, it tells writers to be straightforward, serious, and calm. Don’t use alarming words. Don’t joke. And again, the page contains an example of the content that works.
Macmillan Cancer Support
This is one of Kate’s favourite writing guides as well as mine, because it focuses on people, which is very important for a cancer support organisation: http://be.macmillan.org.uk/AboutOurBrand/Howwetalk/Puttingpeopleattheheartofourwork.aspx.
They really think about the way people are feeling. They clearly have content people who “get it”, who are very concerned about the organisation’s voice and tone, not just a dry style guide.
Examples and mistakes
Kate showed us some examples of where MailChimp got it wrong. For example, a system outage message that started with:
“Happy Monday everyone!”
I liked the openness of MailChimp, in allowing Kate to publicise these times when their content struck the wrong tone.
In contrast, Kate showed some times where the tone is just right. Not too formal or too stressful, Even playful when appropriate. For example, when asking the user to confirm the submission of a document: “This is your moment of glory” instead of something like “Are you really sure you want to submit this now?“
We also looked at some content from other companies where the tone is just right, or not right. I enjoyed these examples, and the way Kate kept the focus on people’s feelings when they come to the content, and how they’ll feel after they’ve read it.
Humour, and being honest
There was plenty more in Kate’s presentation, including two very interesting sections on humour and being honest, with examples of good and bad.
Questions
Kate stopped at a couple of points during the session to answer questions from participants. I’ve noted down the questions and her answers.
At MailChimp, who uses the voice and tone guide and who uses the style guide?
The voice and tone guide is externally available, and is required reading for everyone in the company. Everyone communicates with the external world.
The style guide is internal. It’s available to everyone in the company, but it’s required reading only for the professional writers. For people posting on the company blog, for example, the oice and tone guide is required but the style guide is not. People who don’t consider themselves professional writers are nervous about writing. The voice and tone guide really helps them.
Does every company need voice guidelines?
Every company has a voice. Every company needs to communicate that voice to their staff. They may not need a detailed guide, but they need to describe their personality and make the “this but not that” list.
How long should the voice and tone guide be?
MailChimp’s is pretty long, because they have many different types of content. They need many examples and scenarios. If the company is smaller and does not have so many content types, you can have a much simpler voice and tone guide.
Do you use feedback from users for your voice and tone?
MailChimp does, in a couple of different ways.
Firstly, they have started doing user testing on voice and tone. No data to share yet, because they’ve just started. Kate is really interested in the process a user goes through when navigating through the website. Consistency of personality is important, so Kate is testing people with different types of content. The survey asks questions such as, was this reassuring, or are we trustworthy (with graded answers). Kate wants to make sure the reader feels they are talking to the same person throughout.
Secondly, Kate monitors what people are saying about MailChimp in social media, especially Twitter. When people say they don’t like a particular phrase or part of the content, Kate changes it. She also talks to people at conferences and other meetings.
How do you make sure people are following the voice and tone guide?
Kate looks at all the content regularly, once a month, to check that everyone is on the same page. If you notice patterns in the problems that keep coming up, find the writers and talk to them about the “why” behind the voice and tone.
She also recommends teaching people from the get-go. Share the voice and tone guide. Conduct training sessions. Writers and non-writers alike can “get” the guide, because it focuses on people and emotions.
What do you do if stakeholders don’t agree with the voice and tone guidelines?
The best voice and tone guidelines are true reflections of the people behind the company.
- Make sure that the voice is honest – that it’s a true reflection of why people started the company and what they’re trying to do.
- Probe to see if they’re advocating for a voice that’s not real.
- Talk to the stakeholders about how people connect with a voice that is a true reflection of the company. This can earn you a lot of trust amongst the stakeholders, and will help them realise you’re on the same team. You’re not trying to invent a voice and tone out of thin air.
- Show the stakeholders results. How you would change content, how it changes situations, and a before and after example
Do you localise or translate your content?
Kate acknowledged the challenges of translating slang content into other languages. A lot gets lost in translation.
Kate recommends taking a look at the voice and tone, and humour specifically, and make notes about things that may not work. In some cases, make a choice to let things be. In other cases, you may have to sacrifice some content.
Kate has just started working with their translators on this, and will have more to share soon.
Is there research available for this kind of stuff?
The thing is that the requirements and results are different for each company. There’s not a lot of specific research. But look at companies that you like, and the jokes they make. There are a number of publications that talk about voice and tone, and brand personalities, and honest tones. For example, A list Apart: http://alistapart.com/
In closing, from Kate
Kate recommended that we take a step back and look at the people side of communication. This can solve a number of problems, especially those at the very core of our content. And it can change the result when people read our content.
I loved the quotation from Maya Angelou that Kate closed with:
I’ve learned that people will forget what you said, people will forget what you did, but people will never forget how you made them feel.
In closing, from me
The beauty of this presentation, and of Kate’s style, is that it makes this stuff look easy. Just follow these guidelines, and you’ll be right mate. I’m convinced that Kate is right, and I’m fired up to try this out in practice.
The presentation has excellent content, well delivered, and Kate’s style is authoritative, lively and friendly. Thank you Kate, and thanks too to Adam Churchill of UIE for hosting the seminar.
How to override CSS stylesheets in Firefox
Recently we needed to add some custom styling to pages on our documentation wiki. But we wanted the styling to take effect for our authors only. Other readers should see the pages as delivered by the wiki. So I found out how you can override a web page’s CSS for your browser only.
How do you override CSS stylesheets in Firefox, why did we need to do this, and what other ways are available for overriding CSS?
How to do it in Firefox
Here’s how to override a web page’s CSS styles in your browser. You can override as few or as many of the CSS styles as you like. These changes will apply to you only. They will not affect other users of the site.
You could add the CSS (see code box below) to your browser using Firefox’s Web Developer, or Greasemonkey, or another web developer tool. But then the changes you make are temporary – they last only for a single session.
Instead, when using Firefox, you can put your custom CSS into the userContent.css file on your own computer. That file is located in the chrome folder of your Firefox profile. Provided you include the ‘!important‘ directive, the CSS in this file will override the CSS applied by the designer of the web page.
I’m using Firefox on Windows 8. This works for me. To edit your your userContent.css file:
- First you need to find your Firefox profile. In Firefox, choose Firefox > Help > Troubleshooting Information. The “about:support” page will open.
- Under “Application Basics”,
- On Windows and Linux, depending on Firefox version, choose Show Folder (Windows) or Open Directory (Linux) or Open Containing Folder.
- On Mac OS, choose Show in Finder
A folder will open in Windows Explorer (or I assume Finder, etc). This is your Firefox profile.
(It’s probably in a really weird spot. Mine is inC:\Users\User\AppData\Roaming\Mozilla\Firefox\Profiles\oz848lnl.default\chrome.) - Look for the chrome folder inside your profile folder. If it’s there, open the folder. If it’s not there, add the folder and then open it.
- Look for a file called userContent.css in the ‘chrome’ folder. If it’s there, open it in a text editor. If it’s not there, add the file and then open it in a text editor.
- Add the CSS and wrap-around text shown below.
- Save the file.
- Restart Firefox.
Content of userContent.css
The first and last line are the wrap-around text required for the userContent.css file. Everything between is the CSS.
@-moz-document domain(YOUR.DOMAIN) {
} |
@-moz-document domain(confluence.atlassian.com) {body { font-family:'Comic Sans MS', cursive; }} |
Alert: The above styling will make you either the most popular or the most scorned person in the world. All credit to Don Willis for the CSS. 
Our use case
Do you keep scraping your cursor madly around the page on our documentation wiki, looking for the ‘Tools’ option? Are you worried that you don’t have edit access to the pages, because you can’t see the ‘Edit’ button?
We have applied the so-called Sexy Docs look and feel to the documentation spaces. Sexy Docs hides the ‘Tools’ and other options, to make a smoother reading experience. At the moment, Sexy Docs is just a bunch of CSS applied to the space. We have plans to convert it to a plugin. The plugin will be able to make the options visible to logged-in users who have the relevant permissions.
In the meantime, you need to override the CSS if you want the options to be visible without your having to hover over them.
Content of userContent.css, including the CSS to show the wiki tools
The first and last line are the wrap-around text required for the userContent.css file. Everything between is the CSS. In this case, it contains the styles we need for our Sexy Docs override.
@-moz-document domain(confluence.atlassian.com) {#navigation ul.ajs-menu-bar:hover { opacity : 1.0 !important;}#navigation ul.ajs-menu-bar { opacity : 0.5 !important;}#browse-menu-link{ opacity : 0.5 !important;}#browse-menu-link:hover{ opacity : 1 !important;}.page-metadata { opacity : 0.5 !important;}.page-metadata:hover { opacity : 1.0 !important;}} |
This CSS makes the following UI elements always visible in light grey, and appear darker on hover:
- Edit, Share and Tools options
- Browse menu
- Page byline (Author, date and time information under the heading)
Hit a CAC page, such as this one: https://confluence.atlassian.com/display/DOC/Planning+for+Confluence+5. You should see the required menu items, as shown in the “before and after” images below.
Before and after
Before:
Unaltered Sexy Docs style
After:
Overridden with custom CSS
Other ways to add the CSS
One of my colleagues pointed out that you can use the Stylish extension in Chrome, and add the CSS via the Stylish configuration screen. There’s a Stylish for Firefox too.
Change management helping customers train their staff
For our recent major product release, we published a change management guide as a quick tool for customers to see what’s changed in the product. The document is called Planning for Confluence 5. This post describes how we went about designing the change management guide, and whether it’s working. I hope this information may be useful to other technical writers and change managers.
This week our development team released a major version of the product, Confluence 5.0, with many changes that will affect the way people work. We wanted to make sure administrators know they will probably need to warn their colleagues before upgrading the wiki. We also wanted to give a good overview of the changes that will affect people’s day-to-day activities.
Defining the audience
The release notes do a good job of describing what’s new in the release. That information is primarily useful to people who are looking to purchase the product for the first time, or renew their existing licences. The upgrade notes tell administrators what they need to know before, during and after the upgrade. For this release, we needed a way of telling everybody else what was coming. Enter the change management guide.
Many organisations, especially the larger ones, develop their own procedures and training material for their staff, incorporating guidelines on using our product. The change management guide is also intended to help the people who produce those guides, as it’s a good indication of the areas of major change.
Are people finding and reading the document?
I’ve put a link on the documentation home page as well as in the upgrade notes. I’ve moved the document to the top of the left-hand navigation panel, so that it hits that sweet spot where people look first and most often. I’ve tweeted about the document, and mentioned it on Google+.
Are people finding it, and are they sticking around long enough to read it?
This report from Google Analytics shows the traffic on the page.
Google Analytics report for the page
Key dates:
- The Google Analytics report covers the period from 10th to 28th February.
- The software release date was 26th February.
- I published the document on 18th February, so that early adopters could see it. (Views before 18th February were therefore all by Atlassian employees.)
- The spike shows the highest number of hits on the date of release (26th to 27th February, in different time zones). The highest number of hits per day is on 27th February, at 486 views.
Interpreting the figures:
- People have looked at the page 2,196 times over the 17-day period.
- The number of unique visits to the page is 1,760 over the same period. So yes, people are finding the page.
- People are spending more than 3 minutes on the page, on average. That would seem to mean they’re reading it, rather than bouncing straight out.
- There’s a 57% bounce rate. In other words, people are reading this page and then leaving, without visiting other parts of the documentation site. That’s a fairly high bounce rate. For this page, I think that’s good thing. The target audience is people who already know what the product does. They don’t need to read the rest of the documentation. They just need to know what’s going to change.
Comparing this page to the Confluence documentation home page:
The home page is the most popular page in the Confluence documentation (apart from an anomaly: a page that tells people how to configure their Java home variable in Windows, which is not specific to our product).
Over the same period of time, the report for the documentation home page shows:
- 12,140 page views
- 9,431 unique page views
- 1.12 minutes average time spent on the page
- 27.8% bounce rate
My interpretation: The new change management page has a surprisingly large number of views in relation to the most popular page. (The number of views of the new page is about 18% that of the home page.) People are spending more time on the change management page than on the home page. People use the home page as a place to click through to other parts of the documentation (hence the lower bounce rate) but they leave the documentation site satisfied, immediately after reading the change management page. Yesssss!
Hehe of course, you could probably interpret the figures differently.
Designing the content of the change management guide
We chose to design the content around the concepts of before and after, which we termed “previously” and “now”. This is the primary difference between this document and the release notes. The focus of this document is on what’s changed, not on what’s new. In fact, I’d go as far as to say that if there is a new feature in the release that won’t disturb the way people work, it doesn’t need to be part of this guide.
This screenshot (it feels weird taking a screenshot of a document!) shows a couple of the “previously” and “now” images we’ve used to illustrate the changes in functionality.
For the full effect, take a look at the document itself. You can click the images to zoom in: Planning for Confluence 5.
Easy to scan
We want people to find the information they need quickly. The page includes a number of pictures as well as words. Most of the pictures are annotated screenshots. The text is important too: People will search the page (Ctrl+F) to find specific topics.
The page has consistency of terminology and structure. There’s a short introduction, telling people the purpose of the document. There are links to related information, in case someone has wandered in off the Internet and landed on the wrong page (“every page is page one”). The table of contents on the right tells people at a glance what’s on the page.
Plenty of headings mean people can scroll down and absorb the content easily. The structural design of putting the “Previously” sections on the left, and the “now” on the right, makes it easy to grok what’s happening.
Aesthetics
The page looks good. We want readers to have a pleasurable experience of the document, leading into a pleasurable experience of the product.
Feedback
Unsurprisingly, given the way life goes on a wiki, the page has turned out to be a handy place for people to comment on the release, and for the product managers to respond. Docs alive!
