Confluence, Tech Comm, Chocolate. Sarah Maddox. technical communication. A wiki as platform extraordinaire for PRESS

Transcription

1 Confluence, Tech Comm, Chocolate A wiki as platform extraordinaire for technical communication Sarah Maddox PRESS

2 Table of Contents I. Introduction 1 1. Welcome to this book 3 Getting passionate about technical communication and wikis 4 How to use this book 7 How we produced this book 10 Disclaimer Acknowledgments 11 Confluence quick start 13 Have fun in this book! 13 References Introducing the wiki 15 Let's talk about wikis 15 What is a wiki? 16 What do people mean when they say "wiki?" 17 The major wiki brands 18 A wiki by any other name 19 Some well known wiki sites 20 Technical documentation wiki sites 22 Do they all look the same? 25 Pluglns, add-ons and extensions 25 Wiki and tech comm 26 What you now know about wikis 29 References Getting to know Confluence wiki 31 Let's talk about Confluence and its makers 32 Introducing Confluence and Atlassian 32 What is in the wiki? 34 Wiki as subversive technology 42 Why do they call Confluence an enterprise wiki? 43 Confluence 4 45 Confluence is now your friend 47 References 47 II. Developing documentation on a wiki Planning your wiki documentation 51 Let's talk about planning your wiki 51 Analyzing your documentation requirements 52 Choosing a wiki 54 Understanding the server and machine 57 Planning your user management and global permissions 58 Dividing your content into spaces 59 H

3 iv Table of Contents Deciding if you need to add plugins 60 Getting to know your wiki 61 Wikitoria 61 What you know about planning your wiki 63 References Getting started on the wiki 65 Let's get a documentation wiki up and running 65 Installing your own Confluence or signing up for Confluence OnDemand 66 Adding users and groups 73 Adding a documentation space 74 Setting permissions 76 Adding the space description 81 Designing the space home page 81 Adding pages and creating the table of contents 84 Kay's chocolate cake: part 1 87 What you have done so far 88 References Developing content 91 Getting acquainted with the Confluence editor 92 The editor in Confluence The editor in Confluence 4 95 Wiki markup explained 96 Editor quick reference guide 102 Editing a page 104 Adding screenshots and other images to your page 107 Drawing diagrams 108 What you have learned about developing content 112 References Structure and style 115 In search of structure, style and branding 115 Adding structure to a page 117 All about macros 117 User macros 125 Structuring a space with the Documentation theme 128 Structuring your chapters and sections 130 Structuring your wiki 136 Categorizing your spaces 136 Customizing the appearance of the wiki 138 What you now know about structuring and styling your wiki 143 References I44 8. Content reuse and templates 147 The quest for consistency and efficiency 147 An overview of content reuse 149

4 Confluence, Tech Comm, Chocolate v Confluence macros for content reuse 150 Best practices for content reuse 151 Reusing images and Gliffy diagrams 153 Content reuse In Confluence A simple example of content reuse 153 A case study of content reuse on a wiki 156 Other interesting bits and pieces 163 Enhanced content reuse via plugins 166 Templates 166 Page templates 167 Plugins for enhanced templates 173 Creating a space template 174 What you now know about content reuse and templates 175 References Findability and searchability 179 Found in this chapter 180 In search of findability 180 The Confluence search 181 A quick guide to SEO 187 More about labels 189 What you have discovered about findability and searchability 195 References Workflow and release management 199 The flow of this chapter 199 Workflow: what's in the box 200 Release management 206 Extended workflow and publishing capabilities 210 Sticky notes for review comments 211 Going with the flow 212 References Importing and exporting content 215 Bouncing into this chapter 215 Why do we need to get content into and out of the wikl? 216 Import and export options summarized 219 Importing from other wikis 222 Importing from Microsoft Word 223 Importing from Adobe FrameMaker 223 Importing Confluence's proprietary XML 223 Importing from DITA XML 224 Importing from DocBook XML 224 Printing pages and manuals 225 Exporting to PDF 225 Exporting to Microsoft Word 226

5 vi Table of Contents Exporting and importing Confluence XML 227 Exporting to DocBook XML 228 Exporting to HTML 229 Exporting to Eclipse Help 229 Exporting to JavaHelp 230 Exporting to epublishing formats 230 Rolling on out of this chapter 232 References Building online help 237 A quick guide to this chapter 237 Introduction to online help 238 A wikl as candidate for online help 239 A simple online help solution 239 Tool tips and embedded help 243 A case study of web-based, context-sensitive online help 245 How this chapter was helpful ; 249 References 250 III. Life on a wiki A day in the life 253 Good morning wiki! 253 A day in the life of a wiki technical writer 254 A few days in the life of a wiki reader 258 A day in the life of a support engineer 259 A product manager alive on a wikl 261 A developer walks into a wiki 263 The sun never sets on a wikl 264 References What's happening on the wiki 267 What happens In this chapter 268 Activity streams 268 Wiki watches and notifications 269 Monitoring updates via RSS feeds 270 Web analytics and usage statistics 274 Summary of this chapter 278 References Going agile 281 In this chapter 281 Introduction to agile methodology 282 The Agile Manifesto 283 Three agile methodologies 285 Technical writing in an agile environment 288 A wikl in an agile environment 292 Special techniques for agile teams 293

6 Confluence, Tech Comm, Chocolate Summary of this chapter 296 References Wiki best practices and advice 301 In this chapter 301 Tips and best practices 302 Answers to some common questions 304 Getting technical 307 Confluence and SharePoint 310 Kay's chocolate cake: part Summary of this chapter 313 References 313 IV. Giving your wiki wings Engaging your readers 317 Getting involved in this chapter 317 Why engage the readers? 318 The documentation as a hub of activity 319 Why use social media? 321 Engaging internal readers and teams 324 Engaging bloggers 325 Engaging everyone 328 Promoting the role of technical writer 328 Features of the wiki that make people visible 332 Tearing yourself away from this chapter 335 References ' Gathering feedback on the documentation 339 Let's talk about our readers talking to us 340 Gathering feedback - why and how 340 Inviting comments on the documentation 341 Adding feedback forms via plugins or other customization 348 External tools for gathering feedback 352 Using Twitter for feedback on your docs 358 The talk of the chapter 358 References Updates by everyman 361 In this chapter 362 A model for collaboration 362 Is It safe to allow readers to update the documentation? 368 Managing updates by everyman 368 Documentation that cannot be updated 372 Safeguarding copyright and intellectual property 373 How to encourage contributions 375 Kay's chocolate cake: part The Perfect Technical Document 377

7 viii Table of Contents References 20. Pages that walk and talk Strolling into this chapter Lively, shiny, and useful too ^ Risks, and how to manage them Video and audio Photographs and other images Presentations and other documents Gadgets Issue trackers Other Integration points Talking about shininess References 21. Twitter, wiki and games All atwitter about this chapter Introducing Twitter Getting started with Twitter 398 Useful Twitter conventions 398 How to embed Tweets onto a web page 400 How to embed Tweets onto a wiki page 400 How to suggest the words for a Tweet 402 Inviting and publishing tips via Twitter 403 Twitter as a medium for release notes 404 Twitter for gathering reader feedback 405 Saving Tweets 405 Interactivity and games in documentation 406 Case study: the Dragon Slayer docs 407 Lessons learned 409 A little bird told you 411 References Doc sprints 415 Sprinting Into this chapter 415 What is a doc sprint? 416 Some examples of doc sprints 417 Planning a doc sprint 420 Fun 426 Demo and retrospective 427 From an organizer's point of view 427 Aftermath 428 A doc sprint hall of fame 429 Unusual kinds of doc sprints 429 A retrospective on this chapter 430 References Q1 39? J3t

8 Confluence, Tech Comm, Chocolate ix 23. Driving wiki development 433 Zooming into this chapter 433 Innovation in the world of wikis 434 Gaps in wiki functionality 437 Ideas for new wiki functionality 441 How to drive wiki development 443 How to develop new functionality 445 Technical writers who are already building plugins and add-ons 445 Zooming out 446 References 446 V. So long, and see you on the wiki 449 A. Getting help with Confluence 453 B. Glossary 457 C. Characters in this book 465 Index 467

9 Confluence, Tech Comm, Chocolate ix 23. Driving wiki development 433 Zooming into this chapter 433 Innovation in the world of wlkis 434 Gaps in wiki functionality 437 Ideas for new wiki functionality 441 How to drive wiki development 443 How to develop new functionality 445 Technical writers who are already building pluglns and add-ons 445 Zooming out 446 References 446 V. So long, and see you on the wiki 449 A. Getting help with Confluence 453 B. Glossary 457 C. Characters in this book 465 Index 467