ffeathers

It’s just a few days away now! STC Summit ’12 is the annual conference of the Society for Technical Communication in the United States. I’m looking forward to greeting old friends and meeting a number of people that I’ve chatted to on Twitter, blogs, and other online places. There’ll be plenty of excellent presentations and good events too.

My own presentation is bright and early on Monday, the first full day of the conference. It’s called Building a Developer Documentation Wiki. Here’s the link for people using the STC social platform, Zerista: Event details: Building a Developer Documentation Wiki.

A number of people have asked me how long it took to write my book, and how much of that time was spent on the actual writing. Luckily I’d thought it would be interesting to know that myself, so I recorded my time from the very beginning of the project. Thank you to Peter Maddox for helping me to turn my dry figures into a pretty chart!

The time tracking starts from mid May 2011, when I began planning the book in earnest. I stopped tracking my time in mid February 2012, when the book became available on Amazon and B&N. The figures include only the work I did myself. Other people put a significant amount of time into the book too. In particular, Richard Hamilton at XML Press did the copy editing and publishing of the book, the illustrator created the cover image and the five images that introduce the parts of the book, and six people worked on the technical review. It would be interesting to know the total time spent by all of us, but I don’t have that information.

Summarising the time I spent on the book

Elapsed time: 9 months
Total time spent on the book: 620 hours
Number of hours spent actually developing content (words and diagrams): 376 hours

So, the time spent developing content was approximately 60% of the total time. I wonder if that’s about average?

Assuming a 5-day week of 8 hours flat-out per day, 620 hours would have taken 16 weeks. That’s approximately 4 months. I did it all while holding down a full-time job – an exciting and challenging one, at that. So, I spent all weekends, all public holidays, and a number of days of my annual leave, on the book. Looking back, I don’t know how I managed it, except that I have a wonderful family who supported me all the way. And it was worth it!

Time per task

This chart shows the number of hours spent per week, on each task. The vertical axis shows the number of hours. The horizontal axis shows a nine-month period by week, from mid May 2011 to mid February 2012. The colours show the different tasks, with a colour-coded key running along the top of the chart.

I’ve totalled the hours per week, since that seems a logical boundary and makes a nice smooth chart. (A daily chart is interesting but very spiky. A monthly chart does not have enough detail.)

Here’s a bit more information about each of the task types. I’ve rounded the figures to the nearest hour in this list:

• Preparation (39 hours): Choose a publisher. Prepare and discuss the initial outline with the publisher.
• Writing (376 hours): Map out the structure of a chapter, write it, do my own review, draw any diagrams necessary, develop test data and take screenshots – everything that goes into developing the content.
• Administrative and technical tasks (66 hours): Sort out the IRS, set up the technical environment, correspond with various people.
• Design (12 hours): Liaise with the publisher and illustrator about the illustrations, book cover, and other design matters.
• Technical review comments (34 hours): Discuss and incorporate feedback from the technical reviewers.
• Promotion (23 hours): Write blog posts, tweet, plan webinars, liaise with companies who may buy the book in bulk. This encompasses just the work done before publication. Promotion ramps up significantly after publication, and is not shown here.
• Index, captions, footnotes (36 hours): Develop the index for the book, add the image and table captions, and formalise the footnotes.
• Copy editing and final proofs (35 hours): Incorporate feedback from the copy editor, and review the final proofs and galleys.

The book

Of course, the amount of time it takes to write a book depends on a number of things, including the size and nature of the book. Here are the vital statistics of my book.

Title: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication

Available: Amazon.com and Barnes & Noble

Publisher: XML Press

Illustrator: Ryan Maddox

Number of pages: 488

Number of words: Approximately 130,000 (excluding the table of contents and the index)

Number of diagrams: I created 11 diagrams to illustrate various concepts. (These are in addition to the drawings created by the illustrator, and a large number of screenshots.)

Dimensions: 9.2 x 7.4 x 1.1 inches

Nature of the book: Technical – see the outline of the book

Yesterday I presented a Scriptorium webcast titled “Collaboration: A hands-on demo using Confluence wiki“. The kind folks at Scriptorium have made a recording of the webinar available, and I’ve uploaded my slides too.

This presentation is about collaboration and what it means to technical communicators, and how we can use a wiki to enhance the experience. I give a hands-on demonstration of creating a technical documentation space on a wiki. You will see how to design a home page using the Confluence editor, macros, and even a touch of Twitter integration. You’ll also see how to draft a page, invite subject matter experts to review the page, and keep track of what they do to your documentation. After walking through the simple workflow of draft, review and publication, I discuss the use of add-ons and plugins to supply more sophisticated workflow functionality.

It was great to get some questions from attendees and answer them at the end of the session too. Having a live wiki up and running was very useful to illustrate the answers!

Webinar recording

Scriptorium has published the recording of the webinar on SlideShare: Webinar: Collaboration: A hands-on demo using Confluence wiki

Slides with speaker’s notes

Once you’ve watched the webinar, you may find it useful to see the slides with my speaker’s notes. The slide deck includes screenshots of the parts of the demo that were live on the wiki during the presentation. The slides available on SlideShare: Slides: Collaboration: A hands-on demo using Confluence wiki.

To see the speaker’s notes, click the tab labelled “Notes on slide n” under each slide (next to the comments tab).

Who is Donna Dark?

Donna is a denizen of my demo wiki. She’s a technical communicator extraordinaire. Take a peak at the webinar recording. You’re bound to bump into her.

I’m presenting a session in a Scriptorium webinar about collaboration and technical documentation. The webinar is on Thursday 26 April 2012. (Actually, the date depends on your time zone. It’s Friday 27th April in Sydney.) The session is called “Collaboration: A hands-on demo using Confluence wiki“. Can you join Sarah O’Keefe and me? We’d love to have you there.

Part of the session is a hands-on demo, because I want to show you what it’s like to work on a wiki. The hands-on sections are interspersed with slides, so that we can discuss concepts and ideas too.

The webinar is free of charge. What’s more, you have a chance to win a copy of my book, Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication.

Webinar details

Title: Collaboration: A hands-on demo using Confluence wiki.

Date and time:

• Thursday, April 26th at 4:30 p.m. US Eastern time.
• Thursday, April 26th at 1:30 p.m. in California.
• Friday 27 April at 6:30 a.m. in Sydney, Australia.
• Find the date and time in your part of the world. You can use the meeting planner at the World Time Server to compare times in different places. For example, here’s a link that compares the times in New York, California, Sydney and London.

Registration: Go to the Scriptorium webcast page.

Another Scribbly Gum tree

I’ve posted a few pictures of Scribbly Gums on this blog. They’re fascinating and beautiful. The name of the tree is similar to the name “Scriptorium”, which gives me some excuse for putting this picture here. And this time, unlike in my previous post about scary webinars, there’s no spider on the tree.

Scribbles made by larvae on a Scribbly Gum tree

Coming soon to your iPad and iPhone: a new text processing app designed for structured, sophisticated documents. I’ve had some fun beta-testing UX Write, an app under development by Peter Kelly at UX Productivity. It’s very cool.

UX Write is in the fairly early stages of development, but it can do a lot already. The screenshots below show the functionality as it is today. It will change.

UX Write stores its content as HTML. It uses WebKit to render the content. WebKit is the browser engine behind Safari and Chrome. Peter also plans to support Microsoft Word and LaTeX in a future version of UX Write.

What UX Write looks like

I love the whole idea of this app, and the philosophy behind the design of the menus: Start off simple, and progressively give access to more complex functionality.

This is a screenshot of a document in UX write on my iPad. (You’ll notice some of the wording from this blog post in the document.) The screenshot shows the specialised keypad that UX Write supplies, with fast access to some handy characters.

A document in UX Write with keypad

Peter has extended the standard keypad to provide quick access to often-used keys. He plans to add more smarts to the choice of quick keys. You’ll notice the forward and backward-pointing arrows on the keypad. They move the text insertion point along the line of text, giving finer and faster control than the standard method of positioning the cursor by touching the screen.

In addition to the usual “Select” and “Select all” options that appear when you touch the text, UX Write has “Select paragrah”.  A very nice touch.

Applying styles to text

You can apply formatting to text. That’s neat.

Formatting text

Even neater is that UX Write supports styles, along the lines of those in Microsoft Word.  What’s more, you can define your own styles too.

Designing and applying styles

I’ve suggested to Peter that it would be great to share the styles across documents, so that you can build up a portfolio of favourite styles.

Inserting figures

The insert menu currently allows you to add figures, tables, cross-references and hyperlinks. When you add a figure, one of the options is to pull it in from your photo album on the iPad or iPhone.

Inserting an image from your photo album

Cross-referencing

You can insert headings, tables and images (figures) and then add references to them. The hyperlinked words “Table 1″ in this screenshot are an example of such a reference.

Adding cross-references

Document outline

The outline shows the structure of your document, and you can click the sections to jump to the relevant part of the document. I think Peter has more plans for this option too. In future, you may be able to move sections around within the outline.

Document outline

Getting the document out of UX Write

And this is where it starts getting really exciting! You can already print the document, convert it to PDF, email it, and open it in Evernote and Dropbox. The print and PDF outputs do not yet support page headers and footers, but those are in the pipeline once the Word and LaTeX support are available.

Exporting content from UX Write

Storage

You can choose from three storage locations for your document: Dropbox, the iPad or iPhone, or a WebDAV server. Pretty awesome!

UX Write storage locations, showing the files on Dropbox

A cool thought: Confluence wiki supports WebDAV (although the configuration is a bit fussy). Peter Kelly is thinking about the possibilities of integrating UX Write with Confluence and other content management systems.

Would you like to be a beta tester?

Here’s the great thing about beta testing this app: Peter Kelly works fast. When I sent my first batch of suggestions to him, he’d already implemented a number of them and had the next beta build ready for testing! If you do decide to sign up as a beta tester, expect a fast ride. He’s also very receptive to ideas and discussion.

I’ve been doing the testing on the bus, on the way to and from work. I started this blog post that way too. This is exactly the use case Peter is aiming at: working on your document on the run.

Visit the UX Write website or drop Peter Kelly a line at peter@uxproductivity.com. He’s especially keen to hear from people who spend their lives writing complex and professional documents. That’s us, folks.

Last week I was co-presenter in a webinar. It was an interesting, invigorating and fun-filled experience. There was even enough of a dose of terror to give a pleasant buzz afterwards. Since then, I’ve been musing about the role of webinars in technical communication. I’d love to know what you think, and hear any stories of your own webinar experiences. Are webinars a good tool for technical communication? Can we and should we be thinking about doing more of them?

The details of the webinar itself are in two earlier posts: the invitation and the report, which includes a link to the recording.

The plus points about webinars as tech comm tools

We can gain new insight into the product that we’re documenting. When putting together the material for the webinar, I realised it was a great opportunity for me to think of the product in a different way. I didn’t want to repeat the material that’s in our documentation. Instead, I took a look at the product as it’s seen by a large group of customers and by the developers who build the product and its add-ons: a wiki as extensible platform.

A new slant in the user assistance for a product is valuable to the audience too. It gives them another way of taking advantage of the product and of the community of people that provide services around the product. By coming at a product from a different direction, people gain a broader understanding of it and will be able to make deductive leaps when using the product for their own requirements.

One attendee tweeted:

“it’s a bit embarrassing to learn so much in 1 hour after 8 years of using [the product]“.

Thanks for that tweet! It was very rewarding to hear. And I don’t think it should be embarrassing. Instead, it proves the point that a new angle can work wonders.

There’s a strong aspect of marketing in a webinar. You’re representing your company and the product. A webinar provides a focal point for buzz generation. Tweets and blog posts flock around the webinar, both in the leadup and in the report and analysis afterwards. This marketing aspect ties in well with recent discussions in the technical communication world, about our changing role. Maybe webinars are a good way of adding value to our organisations, over and above the day-to-day tasks of a technical writer?

In preparing for this webinar, I collaborated with our marketing team. They converted my slides to the corporate template. I’d thought my own slides were pretty cool, but Terrence Caldwell (product marketing manager) added a distinctive touch of class. Thanks Terrence! The marketing team also handled all all the organisation of and hosting of the webinar. Our technical writing team often collaborates with the marketing team on special projects and documents. It’s great to learn from them – a mutually enriching experience.

Another plus point was working with co-presenters on the webinar. As the first speaker, I made sure that my presentation introduced the other two speakers, and included some material that would act as a lead-in to their sessions. I loved sharing the responsibility with them, knowing that their different viewpoints would make the webinar a good learning experience for the attendees. I have learned a lot from their presentations too.

Interaction with customers and other interested people is another good result of a webinar. During the session, people asked questions by typing them into the online chat. I was kept very busy answering them! Afterwards, many people have tweeted comments, sent email messages, and added comments to blog posts.

Finally, preparing for and presenting the webinar was invigorating and fun. It’s given me new ideas and new energy. I recommend it to anyone who’s brave enough to sit in a room and talk to the ether without knowing what the ether is thinking.

The cons

Preparing for a webinar is time consuming, and it’s hard work. We need to weigh up the effort involved and the resulting benefits to the company. Our marketing team is enthusiastic about webinars as a way of engaging customers. They also see the value of having a subject matter expert give the presentations. We sometimes invite external speakers, in so-called “voice of the customer” webinars. From that point of view, it makes sense for a technical writer to present a session about using a wiki for technical documentation.

The technology is good, but things can go wrong. For our webinar, we had one presenter in Australia (that’s me), one in Europe, and one with the webinar hosts in the United States. The person in Europe had problems with his Internet connection, and we had to delay his presentation while he searched for a better line. Luckily, we could just shuffle the order of two of the presentations, and it all worked well in the end.

Time zones can be a problem. For me, the webinar started at 1 a.m. Yes, the dead zone! I was happy to be awake at that time, but of course not many other Australians were able to attend the live webinar. Instead, we recorded the session and it’s now available online.

Presenting a webinar is scary. But that’s part of the fun.

So, what’s it like to present a webinar?

Kai Weber wrote a great post recently: So what’s it like to present a tech comm webinar? I’ll just add a bit here too (repeated from my earlier post announcing the webinar recording).

It felt a bit odd, sitting all alone and  speaking into the ether at 1 a.m, hoping that people were listening. It was great when I saw all the questions flooding in, and knew that people really were there. The webinar hosts later told me that more than 200 people attended. That’s so cool.

One tip I’d give to people who are planning to take part in a webinar: Practise beforehand. You’ll need to play with the webinar software, and to run through your presentation. The software is fairly easy to work with, so one practice session is enough to get to grips with that.

Running through your presentation is even more crucial. I’d recommend doing the run through at least twice. Also, do it in the same place and if possible at the same time as the real event. Speak your presentation out loud. You’ll feel like a banana (in other words, a bit silly) but it’s better to feel that way when you’re practising than during the actual event. Why should your practice session be at the same time as the actual event? It helps you to identify any possible hazards, such as loud noises or the need for an extra light. In my case, I decided to hold my practice session during the day time instead of at 1 a.m. As a result, I didn’t realise how dark it would be in the room where I was huddled at the bottom of the house, trying not to wake everyone else. So I had to rush around looking for an extra light just before the webinar started!

Something almost as scary as presenting a webinar

This photograph is quintessential Australia. It shows a spider on a web attached to a Scribbly Gum tree. I snapped it while out walking in the bush this morning.

Spider on web on Scribbly Gum tree

On Thursday I was a co-presenter in a webinar about Confluence wiki as a platform for technical documentation. The recording of the webinar is now available, as well as my slides, and a wiki page for discussion and questions.

The recording

The video is available on YouTube:

The slides with speaker’s notes

The slides for my part of the webinar are available on SlideShare: Confluence as a platform for technical documentation.

To see the speaker’s notes, click the tab labelled “Notes on slide n” under each slide (next to the comments tab).

Wiki page for discussion and questions

The recording, slides and other information are also on a page on the Atlassian documentation wiki: Confluence as a Platform for Technical Documentation Webinar. Drop in there to see what people are saying.

Congratulations to the prize winners!

Twelve lucky attendees won prizes in a draw after the webinar. Congratulations all! The names of the winners are announced in an Atlassian blog post.

Webinar includes sneak previews of new wiki tech comm products

For an overview of the three sessions in the webinar, take a look at my earlier post: Invitation to join me in webinar about Confluence and technical documentation.

Just to entice you, here are a couple of hints about what my co-presenters talked about and demonstrated during the webinar.

Tobias Anstett from K15t Software talked about his company’s vision that wiki technology is the future of technical documentation. He gave two demos of the Scroll DocBook Exporter and the Scroll EPUB Exporter, which you can use to convert Confluence content to DocBook XML and EPUB formats. Tobias also hinted tantalisingly that K15t Software will announce two new products at Atlassian Summit in May. The two products focus on the planning, creation and quality assurance parts of the documentation life cycle. There’s also a solution in the works for wiki-based online help, including the ability to add user comments. Exciting!

Darryl Duke from Stepstone Technologies demonstrated the Zen Foundation theme. I loved his point that collaboration is and always will be about human interaction. So, to get people to use a wiki, familiarity and visual integration are very important. People need to feel that they belong on the wiki. The wiki must be a high quality reflection of the community and brand that it serves. With the Zen theme, you can produce a very sophisticated look for your wiki site. Zen also customises the wiki editor. Darryl gave a very cool demo of how you can drag and drop sections of a page, edit a section as an independent block of content, and use master pages to define standard page layouts. He then gave us a sneak peek of a new interactive brand designer that Stepstone Technologies will launch at Atlassian Summit in May. (In the Zen theme, the brand is the collection of CSS and images that determine the look and feel of your site.) Very smooth indeed!

What’s it like presenting a session in a webinar?

At the beginning of this post, I wrote that the webinar took place on Thursday. Actually, it was 1 a.m. on Friday morning here in Sydney! It felt a bit odd, sitting all alone and  speaking into the ether at 1 a.m, hoping that people were listening. It was great when I saw all the questions flooding in, and knew that people really were there. The webinar hosts later told me that more than 200 people attended. That’s so cool.

One tip I’d give to people who are planning to take part in a webinar: Practise beforehand. You’ll need to play with the webinar software, and to run through your presentation. The software is fairly easy to work with, so one practice session is enough to get to grips with that.

Running through your presentation is even more crucial. I’d recommend doing the run through at least twice. Also, do it in the same place and if possible at the same time as the real event. Speak your presentation out loud. You’ll feel like a banana (in other words, a bit silly) but it’s better to feel that way when you’re practising than during the actual event. Why should your practice session be at the same time as the actual event? It helps you to identify any possible hazards, such as loud noises or the need for an extra light. In my case, I decided to hold my practice session during the day time instead of at 1 a.m. As a result, I didn’t realise how dark it would be in the room where I was huddled at the bottom of the house, trying not to wake everyone else. So I had to rush around looking for an extra light just before the webinar started!

Doing the webinar was interesting and fun. Thanks so much to everyone for attending, and to Terrence and Matt at Atlassian for holding everything together behind the scenes. And congratulations to Tobias and Darryl on their excellent presentations. Co-presenting is the way to go!

This tip is for people using the Copy Space plugin on Confluence wiki. If you’re copying a large space, you may see an HTTP 500 or HTTP 504 server error a few minutes after starting the space copy. Don’t panic. It’s likely that the copy process is still going on. Whatever you do, don’t close the browser tab or window until you know for sure.

It happens to me often, and it happened in a rather spectacular fashion earlier this week. I’m letting you know, in the hope that I can save you from a moment of panic. Or, as in my case this week, from a few hours of unnecessary frenzy.

About the HTTP 500 and HTTP 504 errors

When you get an HTTP 500 error, your browser window displays a message something like this:

• 500 Internal Server Error
• Internal Server Error
• HTTP Error 500

The error message is a bit useless. It doesn’t give you much information, and it sounds very dire. Basically, it means that something has gone wrong and the server can’t give you more information. This is the error we get when using the Copy Space plugin on our production documentation wiki.

I’ve also seen an HTTP 504 error appearing in the same situation on a test server. It seems that the server configuration determines which error you get. HTTP 504 is a Gateway Timeout error. That’s a bit more helpful and a little less scary.

What to do if you get an HTTP 500 or 504 while copying a space

First, wait a while. It is most likely that the front end has timed out, but the copy process is still happening in the background. Do not close down your browser.

Open another browser window or tab, and try going to the address of your new space. The space will become available when the copy operation has finished. Keep trying.

How long should you wait? Ah, now there’s the rub. The copy operation can take anything from a few minutes to a few hours, depending on the size of your space. Until this week, I would have said 2 hours was the maximum time to wait. This week, one of our spaces took 5 hours to copy. I guess the answer is: It depends on your previous experience with copying spaces on your wiki.

When the waiting period has gone on too long, raise the alarm with your system administrators. Ask them to examine the logs to see what has happened, and to determine whether the process is still running.

If you have no joy there, start the copy process again.

What is the Copy Space plugin?

The Copy Space plugin is an add-on that you can install into your Confluence wiki. It gives you a way to copy the content of a space to a new space, with a new space key. One of the Confluence developers wrote this plugin for the Atlassian technical writers, and it’s available for everyone else to use too. It is not a supported plugin, but we use it all the time. It would be very difficult to do without it.

There’s a request for the Copy Space plugin to be supported and bundled with Confluence: CONF-14198. If you like, you can vote for and comment on the issue. If the plugin were supported and bundled, we could ask for better handling of long-running tasks.

Banksia flower

I love the colours of this Banksia flower I saw when walking in the Australian bush. The flower head is made up of hundred of tiny individual flowers. (Ref.) Perhaps 500, or even 504?

I’ll be presenting a session at a webinar on Thursday 12 April (in most time zones), hosted by Atlassian. The webinar is titled “Confluence as a platform for technical documentation“. We’re packing three sessions into this webinar, so it should be fun and full of information. The other presenters are Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. I’d love it if you could join us. It’s free.

I’m excited about this webinar, because it’s about an aspect of wikis that I’ve come to see as very important: the fact that wikis are extensible, versatile, and built to be so. As a result, there’s a community of enthusiastic developers and innovators who devote a good deal of time to extending wiki functionality, challenging the wiki software owners, and keeping the wiki at the forefront of web technology.

I think that we technical communicators can use this characteristic of wiki technology to great advantage. Technical communicators are in the thick of things. We work in diverse environments, innovate, share ideas, collaborate, and write about the latest technologies and methodologies. We need a tool that can keep up with us.

This webinar focuses on Confluence, the wiki developed and sold by Atlassian.

Webinar details

Title: Confluence as a platform for technical documentation

How to join:  Go to the webinar registration page.

Date and time: The registration page has a neat time zone converter. Here is the time in some time zones:

• US Pacific time: Thursday 12 April 2012 at 8 am
• US Eastern time: Thursday 12 April 2012 at 11 am
• Amsterdam time: Thursday 12 April 2012 at 5 pm
• Sydney time: Friday 13 April 2012 at 1 am (yes, that’s right, 1 am)

Length: 60 minutes

What’s in the webinar

People from two different plugin development companies are joining me to present parts of the webinar: Tobias Anstett from K15t Software, and Darryl Duke from Stepstone Technologies. That’s so exciting!

I’ll kick off, with a discussion of Confluence as an extensible platform.

• The extensibility and versatility of the wiki stood me in good stead recently, when I used Confluence to write and publish a book. I’ll talk about the benefits of writing on the wiki, the plugins that we added to the wiki to provide the functionality we needed to produce the book, and how we worked with the plugin developers to extend the functionality even more.
• Moving to the broader arena of technical documentation, we’ll look at some typical requirements of a documentation tool. I’ll discuss whether core Confluence functionality satisfies those requirements, and point out the plugins that we can add to give us what we need.
• I’ll also show how technical communicators can get involved in the development of wiki technology.

Next up is Tobias. The K15t team develops a number of Confluence plugins specifically for technical documentation. The company’s vision statement  is, “We believe that wiki-based technologies will be the future for documentation.” Yes! Tobias also spent a lot of time with me and Richard Hamilton, of XML Press, extending the Scroll Wiki DocBook Exporter plugin to enable us to produce a book on the wiki. It will be great to share the webinar with Tobias. His part of the session is called, “Complete the Documentation Life Cycle with K15t” and he’ll show us how to use the K15t plugins in the documentation life cycle.

Darryl will conduct the third part of the webinar, titled “Simplify and brand your Documentation with Stepstone’s Zen”. Zen Foundation is a theme that you can add to Confluence. It is available as a plugin, developed by Stepstone Technologies. A theme changes the look and feel of the wiki site, and can add significant functionality too. I’ve recently worked on the Atlassian Developers site, a Confluence site that uses the Zen Foundation theme. Darryl and the Stepstone team were great in helping us to develop the brand we wanted for that site, and in customising the theme for our needs.

Prizes too

There are some prizes to be won! When you register, your name will be entered into a draw to win one of these:

• One of 10 copies of my  new book: Confluence, Tech Comm, Chocolate: A wiki as platform extraordinaire for technical communication. (Thank you to Atlassian and XML Press for making these available.)
• A Zen Foundation license valued up to $12,000.
• One of K15t’s Scroll Wiki Exporters valued up to $3,600.

Questions and chat

If there’s time at the end of the webinar, we’ll open it up for questions. Come and throw them at us.

This hint is for people who type faster than they move their mouses. Like me! It shows one of the ways of formatting text quickly (bold, italic, bullets, lists, headings) in Confluence wiki. The post could also be called “quick keys FTW”.

I’m using Confluence 4.1.9.

Keyboard shortcuts are your friend

They’re a real time saver. Click the ? on the editor toolbar to see them:

The resulting help dialog shows some of the shortcut keys:

There are more – try the usual suspects too

Most of the keyboard shortcuts will work as you expect. For example:

• Bold text: Ctrl+B or Cmd+B
• Italics: Ctrl+I or Cmd+I
• Undo: Ctrl+Z or Cmd+Z

They’re described in the Confluence documentation: Keyboard shortcuts.

Who cares about content? I do. Passionately. But then I’m a technical writer, so that’s only natural. However, more and more organisations are beginning to realise the value of their content, be it the words and images on their websites, their product documentation, online forums, or any other way in which they make their presence known. Content, especially online content, is their primary way of interacting with customers and potential customers.

I’ve just finished reading Alan Porter’s new book, The Content Pool: Leveraging Your Company’s Largest Hidden Asset, published by XML Press. It’s a great read, in Alan’s inimitable story-telling style. If you’re in any way involved in the world of business and its content, then this book will give you plenty of points to think about.

Content matters

The book’s theme is that content is a strategic business asset and should be treated as such. In fact, the final chapter makes the case for appointing a Chief Content Officer (CCO) so that content is managed at senior executive level.

Kudos to Alan for identifying this topic and running with it. It’s a topic that all organisations need to pay attention to. High-quality content, well managed, is especially of critical importance to commercial organisations that target a globally distributed customer base. Wise and smart content management is the way to make and save $$.

Great stories

Thoughout the book you will find stories drawn from Alan’s own experience, illustrating his points and making the book a joy to read. It’s like sitting down at the fireside with a friend, discussing your troubles and mulling over the possible solutions.

This is a great quotation: “I’m a writer. I take the truth and give it scope.” (From the film “A Knight’s Tale”, quoted on page 82.)

I loved chapter 11, “Answers are the Answer”, and its tale of the purple monkey (page 134). A senior technical writer at a certain organisation was convinced that no-one ever read the “Description and Operation” documents that he produced.  So he had taken to adding the words “purple monkey” in the middle of the documents, completely out of context and in the middle of a sentence. No-one ever complained.

New perspectives…

On page 36, Alan writes, “With all this talk of the future and new media, don’t forget about your legacy information and your older, or disconnected, audience. Paper is still the default for the vast majority of people in the world. It is still the best user interface and delivery mechanism ever created.”

Those are good words. They gave me a new perspective on paper.

Alan makes the point that we need to design content that will still be readable in a few years’ time. And that will also be available on that legacy format, paper. For that reason, we should develop content in a presentation-neutral format.

…leading to my own musings

This led me to thinking about longevity of content. How true is it that our content needs to stand the test of time? Some of it must, of course. But perhaps the vast majority is disposable, as is so much else we use. I guess that part of content management is the ability to recognise and delineate the content that needs to be in a format that will survive.

Focus on questions and considerations

In some sections of the book, I thought that perhaps there was plenty of attention paid to the problems an organisation faces concerning its content, but perhaps not enough information about the solutions. An example is chapter 4, which talks about the language we use in our content and the problems we may encounter if we get it wrong. Only one solution is proposed: the use of a controlled language, which I think may not suit all environments. Chapter 6, on collaboration, is also a bit light on the “how to” details. Chapter 13 is about choosing a technical solution: a tool or platform for content development and management. It has good information about the questions you need to consider, but no details about the technologies available and the relative capabilities of each.

On the other hand, the book makes you think. That’s what you want a book to do.

What about the picture on the cover?

Ellis Pratt has written a great review of The Content Pool over on the Cherryleaf Technical Author’s Blog. But I disagree with Ellis about the picture on the cover of the book. Douglas Potter has done an excellent job. The book is attractive and engaging, and the artwork reflects the informal style of the content.

What do you think? (Purple monkey.)

Highly recommended sections of the book

Chapter 9 has a useful section on the points to consider when choosing a new standard for your content and for the processes that surround its production. Pages 104-9 list the questions to ask, followed by the tasks to follow when pursuing your selection strategy.

Chapter 12 covers user-generated content. It’s a very useful introduction to this complex topic. Alan also touches on the question of integrating a platform that allows user contributions with a more structured authoring environment, as recommended in the earlier section on round tripping in chapter 10.

Summing it up

Sit back, grab a glass of something warm and comfortable, and settle in for a good read. By the end of the book you’ll have a much clearer understanding of what content is, why it’s so important to an organisation’s well being, and the points to consider when setting out to improve your content management strategies.