This is the first post in a series centered around Sarah Maddox’s new book: Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication, published by XML Press. The book is choc-a-bloc full of tips from a technical communicator who has spent the last four years on Confluence. Learn how to harness the wiki’s social and collaborative features, turning technical documentation into true communication. Discover how technical communicators can drive the ongoing development of wiki technology. Over the next 5 weeks, this series will give you a sample of some of the key themes from the book as well as provide you with some tips and tricks for using Confluence for technical documentation.
This post contains material from the book, reproduced with Sarah’s permission.
A day in the life of a wiki technical writer
Ganache is the hero of Confluence, Tech Comm, Chocolate. She is a technical writer at Choc Ink, a fictitious company specializing in software tools for the chocolate industry. Two of those tools are ChocTactics and ChocSpice. Ganache spends most of her day on the wiki.
Image is copyright © Ryan Maddox, 2012
9 am. Check the wiki notifications
The sweet, spicy aroma of nutmeg and cocoa heralds the arrival of Ganache and her mug of hot chocolate. It is time to see what has happened on the wiki overnight. Ganache opens her email inbox and scrolls through the notifications sent by the Choc Ink documentation wiki.
Ganache bursts into giggles, spraying chocolate froth onto her monitor. A reader has commented about a spelling error on a page, ending his comment with this quip: “It was a little ChocInk to find a typo on such otherwise awesome documentation!”
Ganache fixes the error on the page and adds a comment of her own. “Thank you for pointing out the error. Fixed. Your ChocTactics worked, by the way – I laughed out loud when I read your comment.”
A support engineer named Roald has added a new troubleshooting page, which describes a known issue with the latest software release and provides a workaround that customers can use until the problem is fixed. A quick glance at the notification tells Ganache that the page could do with some technical writer love.
The next notification requires immediate action. A spammer has created a login account on the wiki and added a couple of comments advertising free holidays. Ganache deletes each comment, wondering absently why anyone would think such an advertisement on a documentation wiki is likely to generate sales.
9:45 am. Attend the team standup
All around Ganache, the ChocTactics developers are getting up from their desks, stretching, yawning, and chatting. They group together to form a rough circle.
A standup is a short team meeting, held standing up. It is a phenomenon of agile development. Standups usually happen daily, usually in the morning, and are usually very short. The number of occurrences of the word “usually” indicates that a standup is whatever the team makes of it. The aim is for team members to report what they did yesterday, what they plan to do today, and what roadblocks, if any, are hindering their progress. All team members listen to the reports, and if anyone says anything that affects somebody else’s work, the people concerned get together for a discussion after the standup
Ganache kicks off the proceedings. “Yesterday I started the draft release notes for ChocTactics 2.0 and finalized the updates to the administrator’s guide. Today I will create a new documentation space for ChocSpice, finish the first draft of the ChocTactics 2.0 release notes, and restructure the ChocTactics user’s guide. One of the support engineers has reported a bug in ChocTactics 1.1: the assessment report shows a glitch if the date is the 29th of February. I will work with him to finalize the troubleshooting page.”
10 am. Review the wiki updates
Ganache does a quick review of the troubleshooting page that Roald, the support engineer, has created to address the leap year bug. The page is currently visible to the world, because Roald judged it important to get the information out to customers as soon as possible. Ganache agrees with his decision and is confident that the information supplied is correct.
She fixes the spelling, standardizes the page structure, and adds contextual information at the top of the page and the related topics at the bottom. She publishes her updates immediately, being similarly confident that she has added value and not added anything technically incorrect. The simple wiki workflow is good for this use case. Edit, update, save, and the updates are immediately visible to everyone who has permission to see the page.
10:15 am. Work on new projects
Choc Ink has formed a development team to work on a new product called ChocSpice. Ganache needs to create a new space on the wiki for the ChocSpice documentation so she and the team will have a framework for the manuals and release notes.
To create the new space, Ganache uses the Copy Space plugin and a space that she has constructed to use as a template. The template contains the skeleton for a user’s guide, administrator’s guide, installation guide, and the other bits and pieces needed in a technical documentation space.
Next, Ganache turns to the documentation for a new release of ChocTactics. She works through the set of features and improvements marked for this release in the project issue tracker, noting those that require a mention in the release notes and those that require a change in the documentation.
The page for the ChocTactics 2.0 release notes currently has page restrictions applied so that it is visible to Choc Ink employees only. Ganache adds and updates items in the release notes, then sends a notification to the product manager and development team asking for feedback. The document will undergo a number of reviews before release date and will be ready for publication with the software release. When the product manager gives the go-ahead, Ganache will remove the page restrictions so that the release notes are visible to everyone who has permission to see the space.
1:30 pm. Do some wiki restructuring
After lunch Ganache tackles a reorganization of the table of contents in the ChocTactics user’s guide. When writing some new pages for ChocTactics 2.0, which is as yet unpublished, Ganache realized that the guide itself could do with some restructuring. She wants to add a new section to the table of contents, move some existing pages into it, and add some new pages specifically for ChocTactics 2.0. The new structure will benefit customers using the current version of the product, as well as being essential when the new version is released. Therefore, Ganache has decided to make the changes on the live wiki.
5 pm. Check the wiki notifications again
Ganache checks her wiki feed again to see what has happened since this morning. A customer has added a comment to the new troubleshooting page, expressing disappointment that the bug exists at all. Roald has already replied, apologizing on behalf of Choc Ink for the inconvenience caused and saying that the fix is under development.
Another customer has added a comment in praise of the new troubleshooting page.
“Thank you for the workaround,” the customer enthuses, “You saved my life! I would just like to point out to other people that this glitch happens only in a leap year, and only on the 29th of February. That’s today. I am sure Choc Ink will release a fix before the next time this bug can affect us, so there’s no need to apply the workaround unless you need the report today.”
Good point, thinks Ganache. She adds a similar note to the wiki page and thanks the customer for the comment. On that happy note, Ganache logs out of the wiki and heads off home.
Stay tuned
Keep your eyes peeled for next week’s post where we’ll talk about how Confluence makes it easy to manage updates to your technical documentation, for everyone.
Buy the book
Meet Ganache, Roald and the rest of the merry band in the book and learn more about wikis, technical communication and chocolate at the same time. Buy Sarah’s book Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication today!
Live Webinar: Confluence as a Platform for Technical Documentation
Thursday April 12th, 2012 | 8:00 AM PST
Join Atlassian technical writer extraordinaire, Sarah Maddox, as she shows how she used Confluence to author her book and shares how you can customize Confluence to fit your technical documentation requirements. Special guests from Stepstone Technologies and K15t Software will demonstrate how their add-ons make it easy to brand your online documentation and facilitate the entire documentation lifecyle with Confluence.
Register now for your chance to win one of 10 copies of Sarah’s new book, a Zen Foundation license valued up to $12,000, or one of K15t’s Scroll Wiki Exporters valued up to $3,600.
Try Confluence today
Give your technical documentation a boost with Confluence. Start a free 30-day trial and see how easy it is to start developing your technical documentation. With licenses starting at $10 for 10 user, OnDemand or Download, you can’t go wrong.
Once you’re up and running follow our comprehensive guide on Using Confluence for Technical Documentation. Guess what? It’s documented in Confluence 🙂
