Blog Archives

Chapter 2 of the adventures of Trilby Trench

Have things improved, or is Trilby Trench still in a pickle? Read A Word If You Please, chapter 2 to find out!

A Word If You Please is the first book in an online fiction series about Trilby Trench, tech writer and action hero. Don’t worry if you missed chapter 1 – you can still read it and get to know Trilby Trench. See the about page on her site. You can also subscribe to updates on the site, to make sure you don’t miss out again. 🙂

What does Stack Overflow’s new documentation feature mean for tech writing?

Stack Overflow has recently announced the public beta release of its new documentation feature. That is, Stack Overflow now provides a platform for crowd-sourced documentation relating to any number of products, for the people, by the people.

For those of us managing the docs for widely-used products in particular, this means our customers may soon have access to an alternative, crowd-sourced documentation set.

What an awesome experiment for us as technical writers to follow! We’ll be able to see at first hand what our customers know they need, in terms of information about our products. Because this is Stack Overflow, the documented products are likely to be APIs, SDKs, and other developer-focused tools and technologies.

What if the documentation on Stack Overflow turns out to be voluminous and extremely useful – where would that leave us as technical writers working on proprietary doc sets? I think it will give us the opportunity to streamline our content, focusing even more than we do now on ensuring our information is up to date, and that our information architecture is the best we can make it.

In other words, we can ensure our target audiences can find what they need, even when they don’t know yet what that is.

Technical writing is hard. Information architecture is hard. The Q&A side of Stack Overflow works extremely well, because it focuses on short snippets of content that answer a particular question. It’s going to be very interesting indeed to see how well the new documentation feature works, with the more narrative demands of technical documentation.

An issue I foresee is that people will be tempted to kick off a topic, and then tire half way through and end up providing a link to the official documentation. Is that a bad thing? Tech writing know-how says our readers find it disconcerting to have to click around to find their information. It’s OK in a Q&A format, but not so good in a tutorial or step-by-step guide.

I really like Stack Overflow’s focus on sample-driven documentation!

I’d love to hear your thoughts on this development. Where do you think it’ll go within the next few months, and how about within the next two years? Will it fizzle into nothingness, or explode into something huge and beautiful? Will the original Q&A form of Stack Overflow merge into the new documentation form, becoming something new?

Can a technical writer write fiction?

Can technical writers do other types of writing, in particular fiction? Oh yes indeed! I’ve just finished reading Dave Gash’s new science fiction novel, The ELI Event. It’s a lot of fun.

I fell in love with the characters, including the non-human ones. I chewed my nails in the tense moments, cried and laughed in the good moments, gritted my teeth when things went wrong. When it was all over I felt great satisfaction at the way things turned out, coupled with that sweet sorrow you get when you finish a good book.

The ELI Event

The ELI Event

Dave is a friend of mine. I met him at a technical communication conference two years ago, and we’ve bumped into each other at a couple of conferences since. He’s great. His other big talent is compiling and hosting geek trivia quizzes. 😉

At first I was worried that knowing Dave would spoil my experience of the book. Would I hear his voice speaking through the text, preventing that essential suspension of disbelief that good sci fi demands and facilitates? Even worse, would I feel obliged to enjoy the book? The answer is “No” on all counts. The book grabbed me from page 2 and pushed me through all the way to the end.

Why page 2? Well, it took me most of page 1 to forget my worries about knowing the author. I’m sure the book will grab you from page 1!

Here’s a challenge 😉

Can you find anything in The ELI Event to indicate that a technical writer wrote it?

Details of the book

Dave Gash provides the book in paperback and in Adobe ePub format. You can order it from his website: The ELI Event

Title: The ELI Event
Author: Dave Gash
Publisher: Dave Gash with Xlibris.

WritersUA 2011 Monday – Quick survey of technical communicators

This week I’m attending the WritersUA 2011 Conference for Software User Assistance in Long Beach, California. There were a number of kickoff sessions yesterday, but today (Monday) is the first official day of the conference. These are my notes from the opening session. If you find any inaccuracies, they’ll be mine.

The opening session was called “Let’s Look in the Mirror and See What We See”, hosted by Joe Welinske, Matthew Ellison and Tony Self. After a quick introduction to the conference by Joe, we moved into the interactive part of the session. This was a quick, interactive survey of the tools, techniques and goals of the technical communicators in the audience. I found it very interesting and attention-grabbing. What a great way to open a conference!

How the survey worked

Each member of the audience had an electronic response pad. The three hosts asked us a number of multiple-choice questions, and we pressed keys on the response pads to register our answers. The survey tool registered the answers immediately and displayed the results as graphs on the screen.

The full results will be posted on the conference community website. I jotted down notes during the session, and wrote this blog post based on those notes.

A touch of fun

At the beginning of the session, Tony chastised Joe for telling Tony and Matthew that blue shirts were the uniform for this session. It turned out that Tony and Matthew had chosen to wear very similar blue button-down shirts, purely by coincidence. Matthew then informed the audience that we could easily distinguish between him and Tony, because Tony was wearing brown shoes and Matthew black. Ha ha, trust this trio to inject some humour right at the start of the conference!

The questions and answers

1) Which actor did NOT grow up in Long Beach?


  • The majority (42%) answered “Snoop Dogg”.
  • The correct answer was “Emilio Estevez”, and this answer got the fewest votes (14%).

This result caused some hilarity amongst the audience and panel.

2) Which TV show has not been filmed at some point in Long Beach?


  • The majority (30%) said “Breaking Bad”. Woohoo, we got it right!
  • But 27% said “CSI: Miami”, which Joe mentioned is almost all filmed in Long Beach!

3) Which skills are most important in your career?


  1. Writing
  2. Understanding of IT
  3. Ability to learn quickly
  4. Knowledge of tools
  5. Interpersonal


  • The majority (45%) said “Ability to learn quickly”.
  • Fewest (5%) said “Understanding of IT”.
  • 9% said “Knowledge of tools”.

4) What’s your favourite way to learn to use a new authoring tool?


  1. Trial and error
  2. Official manual
  3. Third-party book
  4. Classroom training
  5. Live webinar
  6. Self-paced eLearning


  • Majority (42%) said “Trial and error”.
  • Second highest (25%) said “Classroom training”.
  • Fewest (3%) said “Live webinar”.

5) Improving skills in which of the following might best prepare you for the future?


  1. Use of social media
  2. Delivering information via hand-held devices
  3. eLearning design, development and tools
  4. Usability testing
  5. DITA principles/practices
  6. None of the above


  • Majority (35%) said “Hand-held devices”.
  • Second (25%) said “eLearning”.
  • Lowest (8%) said “None of the above”.

6) When asked at a party what you do for a living, how do you respond?


  1. I’m a writer
  2. I’m a technical communicator
  3. I’m a user assistance professional
  4. I work with computers
  5. I’m unemployed, homeless and crashing this party for a meal


  • Majority (42%) said “I’m a writer”.
  • Second (33%) said “I’m a technical communicator”.
  • Lowest (6%)  tied position, “I’m unemployed” and “I’m a UA professional”.

7) Which of the following help controls do you use?


  1. A links
  2. K links
  3. A and K links
  4. Neither A nor K
  5. What the hell are A and K links?


  • Majority (66%) said “What the hell are A and K links”.
  • Lowest (1%) said K links.

This question came courtesy of Tony Self. Of course! He professed himself to be disappointed with the result, but he said it with one of his trademark smiles.

8 ) What’s the biggest challenge to adopting a new tool or process?


  1. Lack of funds
  2. Intrastructure constraints
  3. Resistance from personnel
  4. Enough time to do it


  • Majority (45%) said “Enough time to do it”.
  • Fewest (11%) said “Infrastructure constraints”.

9) Where do you think AIR Help will be 5 years from now?


  1. Widespread
  2. Used in isolated cases
  3. Not sure
  4. What the hell is AIR Help?


  • Majority (37%) said “What the hell is AIR Help?”
  • Close second (36%) was “Used in isolated cases”.
  • Lowest (8%) said “Widespread”.
  • 19% were not sure.

These are interesting results coming from a set of technical communication professionals, particularly from Adobe’s point of view.

10) Have you considered using a wiki for SMEs to review content?


  1. Using one now
  2. Yes, but not doing it
  3. No, but it’s worth looking into
  4. No, we don’t want SMEs (subject matter experts) fooling around with our content
  5. What the hell is a wiki?


  • Majority (33%) “Yes, but not doing it”
  • 26% “No, we dont want SMEs fooling around with our content”
  • 25% “No but it’s worth looking into”
  • 15% “Using one now”
  • 2% “What is a wiki?”

11)  Which of your hosts is known for being somewhat feeble-minded?

In case you hadn’t already guessed, this is just our three panel members having fun. 😉


  1. Tony
  2. Joe
  3. Matt

At this point, Joe attempted to influence results by asking the question in a somewhat vague manner! He also assured us sincerely that he has not rigged the results! Tension mounted.


  • 57% “Joe”
  • 36% “Tony”
  • 7% “Matthew”

12) How do you keep your users up to date on software changes?


  1. Newsletter
  2. Webinars
  3. Blog
  4. Other
  5. We can’t keep up


  • 56% “Other”
  • 19% “Newsletter”
  • 13% “Can’t keep up”
  • 7% “Blog”
  • 6% “Webinars”

Panel members remarked that the high proportion of “Other” is worth investigating, to see how people are coping with this problem.

13) How often do you telecommute to work each week?


  1. Never
  2. Less than 1 day
  3. 1 or 2 days
  4. 3 or 4 days
  5. Full-time


  • 31% “Never”
  • 30% “Less than 1 day”
  • 19% “1 or 2 days”
  • 12% “Full-time”
  • 8% “3 or 4 days”

14) In the past year, what has been your primary method of non-sales contact with users regarding their needs?


  1. In person
  2. Teleconference
  3. Email
  4. Other
  5. No contact


  • 30% “No contact”
  • 25% “Other”
  • 23% “Email”
  • 13% “In person”
  • 8% “Teleconference”

Panel members remarked that the high proportion of “Other” is worth investigating. It could well point to a wide usage of social media.

15) What type of smart phone do you have?


  1. Blackberry/RIM
  2. iPhone
  3. Windows Phone
  4. Android
  5. Noikia
  6. Other
  7. No smartphone


  • 40% “None”
  • 23% “iPhone”
  • 16% “Android”
  • 13% “Blackberry/RIM”
  • 4% “Other”
  • 3% “Windows Phone”
  • 0% “Nokia”

Another report on this session

Chuck Martin has blogged about this session too, over on the 2011 WritersUA Conference Blog.

My conclusion

Kudos to Joe, Matthew and Tony for designing and carrying out such an interesting and attention-grabbing session to open this great conference!

Introduction to agile methodologies

This week I attended a short introductory session to agile methodologies. An Atlassian colleague, Stuart Bargon, gave us a great overview of Scrum, Kanban and Extreme Programming (XP). We also had a brief discussion about how we can improve the integration of technical writing into the agile development process. These are my notes from the session.

To kick off the session, Stuart asked us what we already know and understand about agile methodology. There was an interesting range of answers:

  • One of the technical writers has documented GreenHopper for a year and a half, and therefore understands agile as a use case for that tool.
  • Another person went into details of the scrum and issue tracking procedures he’s experienced in the development teams.
  • Someone else had read the Agile Manifesto and understood the aims, but had never put it into practice in a team environment.

The Agile Manifesto

Stuart discussed each of the principles of the Agile Manifesto, illustrating some of them with examples from his own experience.

  • Inevitably, we dwelled a while on the point about “Working software over comprehensive documentation”. We didn’t come to any specific conclusions though, other than that everything is relative.
  • I said that my favourite principle, and one I think Atlassian does really well, is: “Build projects around motivated individuals. Give them the environment and support they need, and trust them to get the job done.”
  • Stuart pointed out that this one is particularly relevant to technical writers, in that it emphasises the diversity of skills amongst team members: “Business people and developers must work together daily throughout the project.”
  • Another one relevant to us, in our role as technical communicators: “The most efficient and effective method of conveying information to and within a development team is face-to-face conversation.”
  • Concerning the point about self-organising teams: “At regular intervals, the team reflects on how to become more effective, then tunes and adjusts its behavior accordingly.” Stuart pointed out that this is not a licence for a free-for-all. From a management perspective, the idea is to create an environment that gets the team to organise in the way you want it to. People are more motivated if they decide they want to do something themselves.

I found this point interesting: Many of the ideas in agile methodology come from the way Toyota works. In particular, Toyota’s teams regularly stop and examine their work to see how they can improve the quality. See the book “The Toyota Way“.

Agile disciplines

These are the methodologies we touched on:

  • Extreme Programming (XP) – a set of processes
  • Scrum – a lightweight process
  • Kanban – an even more lightweight process

Generally, agile practitioners pick and mix these days. They take bits out of the various disciplines to suit their needs.

Extreme Programming (XP)

We touched on the principles of Extreme Programming. It’s important to note that not many people follow all the principles devotedly. Instead, people take the bits they need. See this diagram of the Extreme Programming project.


Stuart ran through the basics of the Scrum process:

  • Write feature requests as “stories”. You should include the specific persona and the reason that persona wants to perform the task specified.
  • The “product backlog” is the list of stories in order of priority. Stories at the top of the list should be small. The stories at the bottom of the backlog tend to be just ideas and perhaps still rather big chunks. They must be broken down into smaller stories as they approach the top of the list. Some people use the concept of an “epic” to group related stories and keep them together as they approach the top of the list.
  • The “sprint backlog” is the list of stories to be tackled in a particular sprint.
  • The “sprint” is a period (often two weeks) during which the development happens. There’s a planning meeting at the beginning of the sprint and a retrospective at the end. The idea is that each sprint delivers a potentially shippable product.
  • Scrum defines 3 roles: The product owner creates and prioritises the backlog, defines the stories, decides what goes into the next sprint. The scrum master works with the team day to day and is focused on the current sprint, fixing anything that’s stopping the team from working. The team does the development work.
  • When estimating the stories, you try to use the idea of “story points” rather than time. The story points are expressed as a number, based on the relative complexity of the work required.
  • You work out your “velocity” based on the number of points that you have managed to complete during the sprint. For example, if you had an estimate of 10 points for the stories in a sprint, and completed 8 of them during the sprint, then your velocity is 8. You can work out an average over a number of sprints, and use this to compile estimates for your product backlog.

Stuart gave us a number of good sites for information about Scrum:


Stuart remarked that the processes of Kanban are even simpler than Scrum.

The first step is to map the workflow of your development team. Stuart drew a number of columns on the board:

  • Scheduled
  • In development
  • Ready for QA
  • In QA
  • Ready for deployment
  • Deployed (Done)

You then set limits on the columns, determining the number of cards (tasks or issues) that can exist in a column at the same time. For example, the above set of columns might have these limits: 4, 2, 1, 3, 3.

A good guide for setting the limits on the number of cards is the team size. For example, if you have 10 team members, the total number of limits across all the columns should add up to 10.

The idea is that anyone can write a story and put it on the board. You can reorder the items in the “Scheduled” column.

A developer takes the top card from the schedule and puts it into the next column (“In development”). When development is finished, the card moves into the next column (“Ready for QA”).

But you can’t put a card into the next column if the column is already full.

If a card cannot move into the next column, that means that the person who wants to move it must first tackle one of the cards in the column that is blocking the flow. In this way, the work flows through to the last column. Nothing has any value until it’s in the last column. There’s no value in the whole process unless it’s producing a number of cards in the “Done” column.

One of the attendees remarked that Kanban probably requires more behavioural change than Scrum.

Cards: Agile in a Flash

Stuart took us through some of the cards in a pack called “Agile in a Flash”. I’ve found these links referring to the pack: The Agile in a Flash blog and the entry on O’Reilly Media.

The cards cover the principles of standup meetings, retrospectives, values and principles, coding standards, code ownership, test-driven development, story prioritisation, why you would want to use agile methodologies, and more.

Story prioritisation

We took a quick look at how you prioritise stories.

  • First triage the stories. Assign story points, rather than trying to prioritise the stories in order of importance/desirability first.
  • Break them down into smaller stories if necessary to fit into a sprint.

Stuart told us a funny story of a developer who had tried to break a story into smaller stories. The story was a web form that was rather long, with may fields. He broke it down into a number of stories, each containing just one or two fields. Instead, he could have produced the whole form in one sprint, but with less complex validation and business rules. The first approach makes it difficult for testers and technical writers to do their work within a sprint, because there is no story that contains the entire form.

Stuart also discussed ways of prioritising stories by putting them in a quadrant, with axes such as complexity and business value.

In a sprint, it’s best to do the high risk things first because then you can deal with any issues that come up.

Contact with customers

Contact with customers is one of the agile ideals. It’s interesting to note that, as technical writers working at Atlassian, we have quite a bit of contact with customers. We work on a wiki, where people comment on our docs. They also see our names and email addresses on the docs, and email us directly. And they can make requests of us and the development teams via our public JIRA issue tracker.

How can technical writers work within the agile framework?

We didn’t have time to discuss the specifics of how the different product teams work, and how we technical writers can better integrate our work into the processes. Just a few general comments came up.

  • Log the documentation issues in the development team’s issue tracker.
  • Get rid of the lag: the scenario where the technical writers develop the documentation after the developers have finished their sprint. We had a bit of a discussion of the obvious challenges: Things do change during and after the sprint, so the technical writers will need to keep up with the iterative process too.
  • Push back and insist that the developer teams finish stories in a sprint, because otherwise it makes it difficult for the technical writers to do their work.
  • Sit down with the scrum master, explain the challenges and discuss the solutions.
  • Highlight any problems during the retrospective.

We discussed the idea of getting the documentation included in the “definition of done” for a development issue. There are pros and cons. For example, a pro is that the development team will be more aware of the work the technical  writers are doing and of what needs doing. A possible con is an increase in the tension between the development and the technical writing teams.

Stuart mentioned that in an agile team, there’s less of the idea that a team member is a specialist. Rather, each developer can work on any story. This could also work with the technical writers when embedded in the teams. The technical writers can give more input during planning meetings, into the design of a feature and how it will affect other parts of the product. Similarly, developers can do the drafts of the documentation to ensure it is all finished within the sprint. If you use a task board, such as in GreenHopper, you can see quite clearly the stages that the various stories are in. If a number of them get stuck in the “documentation” phase, that will be clear to the entire team. Therefore people will be more likely to jump in and grab a documentation task off the sprint backlog.

Agile pairing

Introduction to agile methodologies

I took this shot a few days ago, of two dragonflies locked in passionate embrace. They don’t look very agile, do they? Actually, they zoomed around quite efficiently, even in flagrante delicto. That’s agile pairing for you.

In conclusion

It was interesting to hear a summary of agile methodologies from an expert in the field. As someone who lives and breathes agile, Stuart was able to condense the essentials into a very short session and add some great titbits of personal experience too. I’m looking forward to the next session, which will cover specifics of the processes followed by the Atlassian development teams. We will discuss how we can better integrate technical writing into those processes. Thank you Stuart for a very useful introduction to agile methodologies.

Update: A few hours after I published this post, Mary Connor wrote an awesome post over on Clever Hamster, entitled How does Agile affect documentation? If you’ve got to the end of my post and want to take the next step, Mary’s is the one for you.

%d bloggers like this: