This is the fourth post in a month-long series centred 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. The blog 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 week we delight you with a collection of hints and tips that we hope you will find useful and fun! This post contains material from the book, reproduced with Sarah’s permission.
Learn about the very first wiki
In times of yore, web pages used to just put themselves up in front of you and that was that. Then along came the first wiki, and our lives changed for ever. Suddenly we could click a button and change the content of the web page. Even more revolutionary was that we could click “Save” and have our changes visible to the rest of the world. Immediately.
On 25 March 1995 the very first wiki site was born. That was Ward Cunningham’s WikiWikiWeb. This protowiki has other names too, including “Wards Wiki” and just plain “Wiki.”
Why did Ward call his site a wiki? The word comes from the Hawaiian “wiki-wiki,” which means quick. Ward’s own words say it best: “I chose wiki-wiki as an alliterative substitute for quick and thereby avoided naming this stuff quick-web.” (From the WikiHistory page on WikiWikiWeb.)
Image is copyright © Ryan Maddox, 2012
Hug your wiki
Know the wiki inside out. Make full use of its best features and be ready to help other people become wiki huggers too. Technical communicators are in an excellent position to do this because they are accustomed to learning a new tool and getting down to the nitty-gritty of its capabilities. In many environments, technical writers use dedicated writing tools that other people in the organization never touch. With a wiki, everyone works on the same platform. People may need help getting started. This is a technical communicator’s chance to shine!
Recognize and reward the community
Tap into the community, including work colleagues, customers, developers, and even the international community of technical communicators. I have found that people, and especially technical communicators, are very generous with their time and skills. Their passion for their role and for helping other people is boundless. It is good practice to acknowledge people’s ideas and contributions. But more than that, it is rewarding and exciting to do so. The online world, and in particular social tools, thrive on a system of give and take.
In this blog series, we’ve touched on ways of engaging the community in the documentation, and of managing contributions from external authors. Read Sarah’s book for indepth guidelines and lessons learned.
Taste the sweetest RSS feed ever
Technical writers need to know when people update the documentation. In our post on managing updates by everyone, we described two handy ways of monitoring updates to wiki pages: RSS feeds and notifications.
Technical writers also need chocolate. The SCANDYBARS blog has the clearest, most delicious-looking pictures of chocolate I have ever seen. The author makes the pictures by cutting the chocolates in half and then scanning them. That’s right, on a digital scanner. It must get a bit sticky, but the results are perfection. Try the sweetest RSS feed ever.
Think “impudence” then say “Confluence”
We all know that we should think “beer-a” when pronouncing “Jira”. But how do you pronounce “Confluence”? Put the emphasis on the first syllable, not the second – think “impudence” rather than “imprudence.”
Know the sweetness of structure
By following the steps in Sarah’s book, you will learn how to use Confluence spaces to structure your documentation set. You can put your spaces into categories, so that readers can choose to see just the spaces relevant to them. Build your manual by defining a tree of pages, each branch representing a manual or a section in the manual. Apply a theme to customize the look and feel. Using the Documentation theme, you can add a header, footer, and navigation sidebar to all the pages in your space.
How about the structure of individual pages? A wiki page is a web page, so it supports the standard HTML layout features. Confluence macros provide additional layout capabilities. Become a macro magician, with the help of a quick reference guide and some specific examples of macros that are handy when designing a page layout.
Did you know that the structure of the chocolate particles affects the taste and texture of the chocolate and that a good part of the chocolate-making process is designed to change its structure? Refining, conching, and tempering affect the crystallization of the cocoa butter particles. Cadbury and wikiHow tell us how it is done. Gummy or snappy, dry-as-dust crumbly or melt-on-the-tongue smooth, it is all in the structure.
Make your own space template
Once you have created the perfectly structured documentation space, it would be nice to save it as a template for use next time you need a new space. Confluence does not have the concept of a space template. Instead, you can create your own by copying your documentation space and nominating the copy as a template. Use the Copy Space plugin to add a space by copying the content of another space. The Copy Space plugin is not supported, but we use it.
Tweeting your release notes? Hold a Tweet-a-Choc
In last week’s post about turning documentation into communication, we mentioned some cool ways of using Twitter in and around your documentation. One of the ideas was to use Twitter as a way of publishing your release notes.
Writing Tweets can be hard work. Everyone knows that the shorter the document, the more difficult it is to write. Now imagine a document that is about 110 characters long, including spaces! That is the length of a Tweet once you have factored in the hash tag and the link to the documentation.
A good way of composing an alluring set of Tweets is to gather the technical writers, product managers, and marketers in a room, supply them with hot chocolate, and brainstorm the release notes. We call such a gathering a Tweet-a-Choc.
Invite other teams to take part in a doc sprint
A doc sprint is an event in which a group of people collaborate to write a specific set of documents. It’s a great way to improve your documentation and build community awareness.
A buzz builds up around the sprint, both within and outside the organization. Sprinters tell their colleagues what they are doing. They Tweet and blog about it. As a result, more people know about the documentation and are therefore more likely to come to the documentation when they have questions. In many cases, the sprinters are developers and other subject matter experts as well as technical writers. Working in a doc sprint helps people feel that they own the documentation, that it is a good resource, and that they can make a valuable contribution to the organization by working on the documentation. They become familiar with the documentation platform and tools and with the content and its structure. They also become accustomed to working with the technical writers and seeing how the skills of the technical writers and other sprinters complement each other. Check out all of the photos in our doc sprint hall of fame.
Hold a tech writer funny hat day
Technical writers in an agile environment churn out documentation updates quickly and efficiently, producing a shippable product and high-quality documentation at the end of every sprint. This is good, but there is little time to step outside the box and try something new. The technical writers need some time to think about innovative techniques to improve the team’s procedures and the documentation itself.
An innovation sprint, also known as “tech writer funny hat day,” is a short period of time set aside for the technical writers to try something new. We’ve held a couple of innovation sprints. Each one lasts a day. The technical writers arrive bright and early, all wearing hats. The funnier the better. Why the funny hats? It is a tactful way of letting people know that the technical writers are otherwise engaged for the day. It also builds team spirit and makes a good photograph. Our innovation sprints have produced some cool results, including the “Tips via Twitter” initiative that we mentioned in last week’s post, and the Busted Stuff Report.
Live Webinar: Confluence as a Platform for Technical Documentation
Thursday April 12th, 2012 | 8:00 AM PST
Join Atlassian technical writer 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.
Stay tuned
While you are salivating over chocolate RSS feeds and hopefully Confluence, don’t forget to check in next week as we wrap up the blog series with a post on driving development and innovation in your wiki.
Buy the book
Sarah’s book is filled with other creative tips and tricks for encouraging the use of your wiki and bringing your technical writing team together. The book also gives in-depth guidelines and lessons learned from all of the projects an events mentioned above. So, what are you waiting for? Buy the book Confluence, tech comm, chocolate: A wiki as platform extraordinaire for technical communication today to learn more!
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.
