A directory of resources inthe field of technical communication.

Maddox, Sarah

19 found.

About this Site | Advanced Search | Localization | Site Maps



The Atlassian Contributor License Agreement Comes of Age

In early March we opened up the Atlassian documentation to the wider community. We added a CC-by (Creative Commons Attribution) license to our product documentation. We invited people to contribute to our documentation after signing an Atlassian Contributor License Agreement (ACLA). At that stage, the ACLA was just starting its three-month trial. The trial period has now ended, and we're delighted to say: it's a go!

Maddox, Sarah. Atlassian Blog, The (2009). Articles>Documentation>Wikis>Case Studies


The Blur Test for Assessing Page Design in Technical Documentation

The “blur test” is a technique for testing the design of a user interface (UI) or an image. The idea is to squint, or to blur the image in some other way, so that you see the areas of contrast and how they attract your attention. Perhaps we can use the blur test to analyse the design of a page in our technical documentation too.

Maddox, Sarah. ffeathers (2010). Articles>Documentation>Usability>Assessment


Content, Standards, Learning and SCORM

Within content domains, the key themes of the information age are being adopted: Modularisation, specialisation, integration and interoperability. Our communication is changing in volume, purpose and channels. The emphasis is more on collaboration and less on expert-to-novice teaching. And there’s a stronger emphasis on openness.

Maddox, Sarah. ffeathers (2009). Articles>Education>Online>Standards


Converting to Structured Content

You’re told that you need to move your content to XML. You have loads and loads of unstructured content. It’s in FrameMaker, Word, other desktop publish applications, or even more fun: it’s on paper.

Maddox, Sarah. ffeathers (2010). Articles>Documentation>Information Design>XML


Getting Content Into and Out of Wikis

As wikis mature, we’re using them for more complex business cases such as technical documentation, business analysis and project management. It’s becoming more and more interesting, if not essential, for wikis to support the import and export of content to and from other formats. Most wikis allow you to convert their pages at least to PDF and HTML. But what of other formats, and what about tools for getting content into wikis as well as out of them?

Maddox, Sarah. ffeathers (2009). Articles>Content Management>Wikis>Documentation


Review: Help Authoring Tool Comparison

Matthew Ellison presented a number of excellent sessions at this conference. His Friday session was called “Help Authoring Tool Comparison”. He discussed what a help authoring tool (HAT) can do for us as technical writers, then did a detailed comparison of a few popular tools.

Maddox, Sarah. ffeathers (2010). Articles>Reviews>Software>Help


How Technical Writers Can Make Themselves Heard

We technical writers are such shy and retiring types! It seems to be part of our make-up. We like to get in the zone, write perfect and beautiful documents, and expect others to see the value of our work. After all, doesn’t the perfection of a well-crafted document leap out at you? Don’t people know we’re the cool dudes who write the docs that rock?

Maddox, Sarah. ffeathers (2010). Articles>Blogging>Technical Writing


I Got Dragons and Tweets in My Documents

There’s a place for a lighter touch in much of the online documentation we write. It’s a delicate balance. On the one hand, it’s important that the writing style does not annoy or offend the reader and does not detract from the content. We also need to be aware of people whose first language is not the one we’re writing in. On the other hand, the occasional touch of humour or personality can focus the reader’s attention onto the page.

Maddox, Sarah. ffeathers (2009). Articles>Documentation>Wikis>Case Studies


Introduction to DITA Conditional Publishing

Conditional processing is a way to determine which content is published at any one time. There are a number of attributes available on most DITA elements. Basically, you use the metadata to filter the content. For example, let’s assume you are writing the installation guide for a software application. You may store all the instructions for Linux, Windows and Mac OS in one file.

Maddox, Sarah. ffeathers (2010). Articles>Information Design>XML>DITA


Linking to External Blog Posts from Our Documentation

A technical writer’s blog on Wordpress Linking to external blog posts from our documentation with 3 comments At work, we’ve just started a new set of documentation pages called “Tips of the Trade“. The project is still in the early stages. I thought other tech writers might be interested, so I’m blogging about it now. There will be a page for each of the products we document. The pages contain a set of links to useful blog posts written by people out there on the www. It’s a way of giving our readers more information and a way of involving external bloggers, developers and authors in our documentation.

Maddox, Sarah. ffeathers (2009). Articles>Documentation>Hypertext>Blogging


Planning a Doc Sprint

A “doc sprint” is similar to a book sprint. We called ours a doc sprint because it focused on technical documentation and on developing a set of tutorials, rather than a single book. We invited a number of developers to join the technical writing team in a three-day sprint, with the aim of producing some quality tutorials on gadget and plugin development.

Maddox, Sarah. ffeathers (2010). Articles>Documentation>Collaboration>Project Management


Reviewing Wiki Documentation via Crucible

I have been playing around with Crucible, Atlassian’s peer code review tool. The latest version of Crucible allows you to review Confluence wiki pages. This is a new feature, so I decided to try it out. Also, I was wondering why you might want to use an independent tool to review a wiki page, when you could instead just add comments to the page or update the page directly.

Maddox, Sarah. ffeathers (2009). Articles>Web Design>Documentation>Wikis


Technical Writing in a Wiki - Single Source Publishing

As technical writers, we always keep our readers' and customers' needs at the forefront of our minds. One of the most basic requirements is that our readers will have access to the documentation. No matter what tool we use to write the documents, we must be able to publish them in various output formats depending on where our readers are and the tools they have at their disposal.

Maddox, Sarah. Atlassian Blog, The (2010). Articles>Content Management>Single Sourcing>Wikis


Twitter as a Medium for Release Notes

I’m going to start with a short introduction to Twitter, mentioning particularly the aspects that I found useful when tweeting release notes. If you’re already a twitterologist, you may want to skip that bit. Then I’ll describe how we’ve used Twitter as a method of communicating the highlights of our release notes.

Maddox, Sarah. ffeathers (2009). Articles>Documentation>Social Networking>Technical Writing


Using a Wiki for Technical Documentation   (PDF)

Is it possible to use a wiki for technical documentation? Yes, most definitely. I started working on a wiki two years ago, with no prior experience of wikis (apart from the occasional encounter with Wikipedia) but with plentiful experience of technical writing. I’ve learned a lot and I’d like to pass on some tips to you too.

Maddox, Sarah. Southern Communicator (2009). Articles>Documentation>Content Management>Wikis


WebWorks ePublisher for Converting Documents to Confluence Wiki

Over the past couple of weeks I’ve had the chance to experiment with WebWorks ePublisher, a set of tools that converts documents from Word, FrameMaker and DITA XML to a number of different output formats. One of those output formats is Confluence wiki. It’s been very interesting, so I thought I’d blog about it and see if anyone else wants to give it a go as well.

Maddox, Sarah. ffeathers (2009). Articles>Web Design>Content Management>Wikis


What Makes a Technical Writer Tick?

Technical writers are Jills and Jacks of all trades. But what really makes a tech writer tick? In this guest post, Sarah Maddox explores that question and comes up with some interesting answers.

Maddox, Sarah. DMN Communications (2009). Articles>Writing>Technical Writing


What Makes a Technical Writer Tick?

Come to think of it, technical writers are pretty weird individuals. And proud of it. You’d have to be, um, unusual, to actually enjoy writing. What goes into the making of someone who does technical writing all day? Rumours are that we’re intensely interested in the exact placement of a semicolon. Well, that’s true of course. But there’s more.

Maddox, Sarah. Communications from DMN (2009). Articles>Writing>Technical Writing>Audience Analysis

Follow us on: TwitterFacebookRSSPost about us on: TwitterFacebookDeliciousRSSStumbleUpon