Sarah Maddox gave a presentation about writing a book using a wiki platform. She outlined a 9 month process involving content creation, administration, artwork, reviews and production. Key aspects included managing permissions, notifications, diagrams, exporting to production formats. Her book "Confluence, Tech Comm, Chocolate" was written on a wiki and is available for purchase on Amazon and through her website.
1. Writing a book on a wiki
Wow, does that even work?
Atlassian User Group
5 May 2012, Sydney
Writing a book on a wiki – it works! by Sarah Maddox Slide 1
1
2. 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.com
Writing a book on a wiki – it works! by Sarah Maddox Slide 2
2
3. Writing a book on a wiki – it works! by Sarah Maddox Slide 3
3
4. It‟s a team effort, right from conception
Writing a book on a wiki – it works! by Sarah Maddox Slide 4
4
5. 9 months‟ labour – the content phase
15 3 3 31 15
May Jun Dec Dec Feb
Submit Content Production
proposal deadline
Writing
Writing a book on a wiki – it works! by Sarah Maddox Slide 5
5
6. 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 setup
Writing a book on a wiki – it works! by Sarah Maddox Slide 6
6
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
Writing a book on a wiki – it works! by Sarah Maddox Slide 7
7
8. 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 review
Writing a book on a wiki – it works! by Sarah Maddox Slide 8
8
9. 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, etc
Writing a book on a wiki – it works! by Sarah Maddox Slide 9
9
10. 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
Printing
Writing a book on a wiki – it works! by Sarah Maddox Slide 10
10
11. Managing reviewers‟ and editors‟ feedback
Permissions
Sharing a page via email
@mentions
Watching a page or a space
Notifications
RSS feeds
Writing a book on a wiki – it works! by Sarah Maddox Slide 11
11
12. Watching a space
Choose “Browse” > “Advanced”
> “Start watching this space”
Writing a book on a wiki – it works! by Sarah Maddox Slide 12
12
13. Setting your notification options
Choose the type of
content you want to
know about
Choose the format of
the notifications
Writing a book on a wiki – it works! by Sarah Maddox Slide 13
13
14. Wiki plugins and add-ons
Writing a book on a wiki – it works! by Sarah Maddox Slide 14
14
22. Contacting Sarah
Email: sarah@atlassian.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
23. Writing a book on a wiki – it works! by Sarah Maddox Slide 23
23
Notas do Editor
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