Speaker’s notes: IntroductionHallo all, and thank you to Dhyana for inviting me to speak today. I’m Sarah Maddox, a technical writer at Atlassian. I’ve recently written a book on a wiki. The book is about writing technical documentation on a wiki. And I wrote it in a wiki. Dogfood for the win!
There’s a book in everyone. The trouble is, it's hard to get it out of you.It's a lot like having a baby.Having the idea is the fun part…
…Then the project grows and grows. It’s a team effort, right from conception.It’s all about the people and collaboration. You work with a loose team. People join at the appropriate time: Author Publisher Artist Technical reviewers Copy editor IndexerSo yes, producing a book is a lot like having a baby. In fact, my book took 9 months of hard labour…
The content phaseAs the author, you submit your proposal to the publisher. Then you start writing.
The content phasePretty soon, you and the publisher get involved in administration and technical setup.
The content phaseThe illustrator comes on board, and you start promotional activities surprisingly early.
The content phaseThings get really busy when the technical reviewers join you on the wiki. Comments fly thick and fast. Your book is no longer your own.
The content phaseNext up are the index, footnotes and cross-references.
The production phaseJust when you thought it was safe to take a breather, the copy editor starts updating your text. Then you check and re-check the final proofs and printer’s galleys. Then you send the book to the printer.Phew, at last, it’s out the door.
Speaker’s notes: Wiki plugins and add-onsIn addition to the core Confluence functionality, we needed some extra smarts to produce the book.This is where Confluence plugins and add-ons come into it.Confluence is an extensible platform.Developers can build plugins or other add-ons that people can install into Confluence.These add-ons can significantly change the way people experience the wiki.This screenshot shows the Atlassian Plugin Exchange. The Plugin Exchange is a website where developers can make their plugins and add-ons available to customers. It’s also a place where customers can look for and download the add-ons they need.
Speaker’s notes: Gliffy for diagramsThere are quite a few diagrams in the book. To produce them, I used the Gliffy plugin. The Gliffy team gave me a free licence for the plugin, which was very generous of them.It was a great experience drawing diagrams for the book.Gliffy is easy to use, and very familiar to anyone who has used desktop drawing tools.Pleasant styles and libraries of images.You can draw anywhere, anytime, because the Gliffy drawing canvas loads in the web page.Gliffy makes image files available that you can provide to the publisher for printing.
Speaker’s notes: Scroll Wiki DocBook ExporterThis is where the Scroll Wiki DocBook Exporter comes into it. DocBook is a type of XML used frequently in the publishing world. The publisher of my book is Richard Hamilton at XML Press. He already had procedures set up, to produce his books via DocBook XML. He runs the DocBook through his custom XSLT processes, to produce a PDF file for the printers and also the ebook formats of the book.This is the first time anyone has written a book on Confluence and then used DocBook in the production processes.The Scroll Wiki DocBook Exporter is a plugin developed by K15t Software. The plugin already existed, but we needed additional functionality to support book production.The K15t team were kind enough to give me a free license for the plugin. Thanks guys!The publisher and I worked with K15t Software to extend the functionality of the plugin:IndexingImage captionsFootnotesThat was a very interesting and rewarding experience. It’s a great example of how we can use plugins and add-ons to bend the wiki to our will!And so now, if you use the Scroll Wiki DocBook Exporter plugin, you can have an index and footnotes in your documents too.
It’s not over ‘til the wiki singsNew in the publishing world is the idea that a book does not end at printing. The conversation continues, amongst readers and authors and the whole wide world.You want to keep readers engaged, get their feedback on the book, and keep them interested with a view to future sales too.What better place to keep people engaged than the wiki?There’s a wiki associated with my book. A few readers have added pages and comments there already. I’m hoping that more will come, especially once I’ve had a chance to publicise it!http://wikitechcomm.onconfluence.com
Writing a book on a wiki Wow, does that even work? Atlassian User Group 5 May 2012, SydneyWriting a book on a wiki – it works! by Sarah Maddox Slide 1 1
Confluence, Tech Comm, Chocolate A wiki as platform extraordinaire for technical communication Wikis and technical documentation Agile environments Social media Crowd sourcing Driving wiki development And more wikitechcomm.onconfluence.comWriting a book on a wiki – it works! by Sarah Maddox Slide 2 2
Writing a book on a wiki – it works! by Sarah Maddox Slide 3 3
It‟s a team effort, right from conceptionWriting a book on a wiki – it works! by Sarah Maddox Slide 4 4
9 months‟ labour – the content phase 15 3 3 31 15 May Jun Dec Dec Feb Submit Content Production proposal deadline WritingWriting a book on a wiki – it works! by Sarah Maddox Slide 5 5
9 months‟ labour – the content phase 15 3 15 3 31 15 May Jun Jun Dec Dec Feb Submit Content Production proposal deadline Writing Admin and technical setupWriting a book on a wiki – it works! by Sarah Maddox Slide 6 6
9 months‟ labour – the content phase 15 3 15 27 3 31 15 May Jun Jun Nov Dec Dec Feb Submit Content Production proposal deadline Writing Admin and technical setup Artwork and promotionWriting a book on a wiki – it works! by Sarah Maddox Slide 7 7
9 months‟ labour – the content phase 15 3 15 27 3 31 15 May Jun Jun Nov Dec Dec Feb Submit Content Production proposal deadline Writing Admin and technical setup Artwork and promotion Technical reviewWriting a book on a wiki – it works! by Sarah Maddox Slide 8 8
9 months‟ labour – the content phase 15 3 15 27 3 22 31 15 May Jun Jun Nov Dec Dec Dec Feb Submit Content Production proposal deadline Writing Admin and technical setup Artwork and promotion Technical review Index, footnotes, etcWriting a book on a wiki – it works! by Sarah Maddox Slide 9 9
9 months‟ labour – the production phase 15 3 15 27 3 22 31 7 5 15 May Jun Jun Nov Dec Dec Dec Jan Feb Feb Submit Content Production proposal deadline Copy edit Final proofs PrintingWriting a book on a wiki – it works! by Sarah Maddox Slide 10 10
Managing reviewers‟ and editors‟ feedback Permissions Sharing a page via email @mentions Watching a page or a space Notifications RSS feedsWriting a book on a wiki – it works! by Sarah Maddox Slide 11 11
Watching a space Choose “Browse” > “Advanced” > “Start watching this space”Writing a book on a wiki – it works! by Sarah Maddox Slide 12 12
Setting your notification options Choose the type of content you want to know about Choose the format of the notificationsWriting a book on a wiki – it works! by Sarah Maddox Slide 13 13
Wiki plugins and add-onsWriting a book on a wiki – it works! by Sarah Maddox Slide 14 14
Contacting Sarah Email: email@example.com Twitter: @sarahmaddox http://twitter.com/sarahmaddox LinkedIn: http://au.linkedin.com/in/sarahmaddox Blog: http://ffeathers.wordpress.com Other blog: http://travellingworm.wordpress.com/Writing a book on a wiki – it works! by Sarah Maddox Slide 22 22
Writing a book on a wiki – it works! by Sarah Maddox Slide 23 23