Confluence as platform for technical documentation
•Transferir como PPTX, PDF•
13 gostaram•8,097 visualizações
Presentation given in an Atlassian webinar, 12/13 April 2012. It's about Confluence wiki as an extensible platform, and how technical communicators can take advantage of the wiki's extensibility.
Recomendados
Mais conteúdo relacionado
Mais procurados
Mais procurados (20)
Destaque
Destaque (20)
Semelhante a Confluence as platform for technical documentation
Semelhante a Confluence as platform for technical documentation (20)
Mais de Sarah Maddox
Mais de Sarah Maddox (14)
Último
Último (20)
Confluence as platform for technical documentation
- 1. Confluence as a Platform for Technical Documentation Sarah Maddox (Atlassian) Confluence as a platform for technical communication Tobias Anstett (K15t Software) Complete the documentation life cycle Darryl Duke (Stepstone Technologies) Simplify and brand your documentation wikitechcomm.onconfluence.com Atlassian webinar, 12 April 2012 Confluence as a Platform for Technical Documentation, by Sarah Maddox 1
- 2. Overview of Sarah’s presentation • Confluence as extensible platform • Developing a book on a wiki • A platform for technical communicators • Add-ons for enhanced functionality • Driving wiki development Confluence as a Platform for Technical Documentation, by Sarah Maddox 2
- 3. Wiki as extensible platform Confluence as a Platform for Technical Documentation, by Sarah Maddox 3
- 4. Wiki as extensible platform Extensible Versatile Ecosystem Confluence as a Platform for Technical Documentation, by Sarah Maddox 4
- 5. Wiki as extensible platform Extensible Atlassian: Core Confluence Versatile Community developers: Add-ons Ecosystem Experts: Integrations and services Confluence as a Platform for Technical Documentation, by Sarah Maddox 5
- 6. Wiki as extensible platform Extensible Atlassian: Core Confluence Versatile Community developers: Add-ons Ecosystem Experts: Integrations and services Customers Confluence as a Platform for Technical Documentation, by Sarah Maddox 6
- 7. 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 Confluence as a Platform for Technical Documentation, by Sarah Maddox 7
- 8. Producing a book on a wiki Confluence as a Platform for Technical Documentation, by Sarah Maddox 8
- 9. Developing the book on the wiki Dogfood Location Diagrams Collaboration Confluence as a Platform for Technical Documentation, by Sarah Maddox 9
- 10. Developing the book on the wiki Dogfood Author Location Reviewers Diagrams Copy Editor Collaboration Artist Confluence as a Platform for Technical Documentation, by Sarah Maddox 9
- 11. Gliffy for diagrams www.gliffy.com Image copyright © Sarah Maddox 2012 Confluence as a Platform for Technical Documentation, by Sarah Maddox 10
- 12. Cool, so now the book is on the wiki Confluence as a Platform for Technical Documentation, by Sarah Maddox 11
- 13. How to get from the wiki to production ? Confluence as a Platform for Technical Documentation, by Sarah Maddox 12
- 14. Scroll Wiki DocBook Exporter www.k15t.com Confluence as a Platform for Technical Documentation, by Sarah Maddox 13
- 15. Technical communicators Keep up with new Work in diverse Collaborate technology and environments methodology Share Ideas Innovate Confluence as a Platform for Technical Documentation, by Sarah Maddox 14
- 16. Technical communicators Skilled Passionate Experienced Full of ideas Confluence as a Platform for Technical Documentation, by Sarah Maddox 15
- 17. Technical communicators Need a tool that can keep up with us Confluence as a Platform for Technical Documentation, by Sarah Maddox 16
- 18. Workflow using core Confluence Image copyright © Sarah Maddox 2012 Confluence as a Platform for Technical Documentation, by Sarah Maddox 17
- 19. Add-ons for enhanced workflow • Configurable workflows • Shared workflows www.comalatech.com • Content publishing • Live forms www.frevvo.com • Conditional routing • Digital signatures And more Confluence as a Platform for Technical Documentation, by Sarah Maddox 18
- 20. Look and feel with core Confluence Confluence as a Platform for Technical Documentation, by Sarah Maddox 19
- 21. Look and feel with core Confluence Themes Logos CSS Velocity layouts Color Schemes Site home page Confluence as a Platform for Technical Documentation, by Sarah Maddox 20
- 22. Look and feel with theme plugins • Zen Foundation • RefinedWiki • Builder • TechTime Blog • BlackBerry • iPhone and iPod Touch • And more plugins.atlassian.com Confluence as a Platform for Technical Documentation, by Sarah Maddox 21
- 23. Zen Foundation theme Confluence as a Platform for Technical Documentation, by Sarah Maddox 22
- 24. Single source publishing No wiki is an island Confluence as a Platform for Technical Documentation, by Sarah Maddox 23
- 25. Importing content into Confluence Import Format Tool Another Confluence The Confluence XML export and import tools are useful for wiki downloading the content of a space, or an entire site, and uploading it into another Confluence site. Other wikis The Universal Wiki Converter is a standalone tool that assists in converting pages to Confluence format from other wiki formats. Microsoft Word Confluence's built-in Office Connector imports a Word document and converts it to one or more wiki pages based on the criteria you define. It processes one Word document at a time. WebWorks ePublisher provides a set of standalone tools for converting Word documents to Confluence, based on custom styles and formats. Batch processing and scheduling are available. Confluence as a Platform for Technical Documentation, by Sarah Maddox 24
- 26. Importing content into Confluence Import Format Tool Adobe FrameMaker WebWorks ePublisher converts FrameMaker documents to Confluence DITA XML DITA2wiki is a standalone tool that converts DITA XML documents to Confluence format and uploads them into the wiki via a set of Ant commands. WebWorks ePublisher offers a set of standalone tools for conversion and import from DITA XML to Confluence wiki. DocBook XML The DocBook import plugin is a Confluence plugin that converts DocBook XML to wiki format and imports the pages into a Confluence space. Confluence as a Platform for Technical Documentation, by Sarah Maddox 25
- 27. Exporting content from Confluence Export Format Tool Another Confluence The Confluence XML export and import tools are useful for downloading the wiki content of a space or an entire site and uploading it into another Confluence site. Print The browser's print option will print a Confluence page. Export to PDF for sophisticated printing options. PDF Confluence's built-in PDF export converts a selected page or pages into a single PDF file and provides customized layout and stylesheets. Scroll Wiki PDF Exporter, a Confluence plugin, offers a PDF export with flexible themes for configuring layout and styles. Microsoft Word Confluence's built-in Word export performs a basic conversion of wiki content to HTML and applies some predefined Word CSS stylesheets. It processes just one page at a time. Scroll Office is a Confluence plugin that exports Confluence pages to Word based on custom templates. You can export a single page or a hierarchy of pages. Confluence as a Platform for Technical Documentation, by Sarah Maddox 26
- 28. Exporting content from Confluence Export Format Tool DocBook XML Scroll Wiki DocBook Exporter is a Confluence plugin that converts a selected page or pages to DocBook XML. HTML Confluence's built-in HTML export converts a single page, a selection of pages, or an entire space to HTML. The Scroll Wiki HTML Exporter is a Confluence plugin that exports content from Confluence pages to styled HTML files. Eclipse Help The Scroll Wiki EclipseHelp Exporter is a Confluence plugin that exports content from Confluence to Eclipse Help format. JavaHelp The Scroll Wiki JavaHelp Exporter is a Confluence plugin that exports content from Confluence to JavaHelp format. EPUB The Scroll Wiki EPUB Exporter is a Confluence plugin that exports Confluence pages to EPUB format. Confluence as a Platform for Technical Documentation, by Sarah Maddox 27
- 29. Many, many more add-ons • Content reuse • Metadata • Templates • Diagrams and mockups • Social media integration • Website and application integration • You name it plugins.atlassian.com Confluence as a Platform for Technical Documentation, by Sarah Maddox 228
- 30. Confluence CLI by Bob Swift https://plugins.atlassian.com/plugins/org.swift.confluence.cli Confluence as a Platform for Technical Documentation, by Sarah Maddox 29
- 31. Plugins in Atlassian OnDemand http://confluence.atlassian.com/display/AOD/Atlassian+OnDemand+Plugin+Policy Team Calendars (commercial) Gliffy (commercial) Content Formatting Macros (free) Table Plugin (free) Confluence as a Platform for Technical Documentation, by Sarah Maddox 30
- 32. How the book deals with Plugins • Detailed in the content • Listed at end of every chapter • Introduced in chapters 2 and 4 • Extolled in chapter 23: Driving wiki development wikitechcomm.onconfluence.com Confluence as a Platform for Technical Documentation, by Sarah Maddox 31
- 33. Wiki as extensible platform Extensible Atlassian: Core Confluence Versatile Community developers: Add-ons Ecosystem Experts: Integrations and services Customers Confluence as a Platform for Technical Documentation, by Sarah Maddox 6
- 34. Driving wiki development Extensible Atlassian: Core Confluence Versatile Community developers: Add-ons Ecosystem Experts: Integrations and services Confluence as a Platform for Technical Documentation, by Sarah Maddox 33
- 35. Driving wiki development Raise requests: http://jira.atlassian.com Join a user group: http://www.atlassian.com/company/community Contact Atlassian: http://www.atlassian.com/company/contact Contact a plugin developer: http://plugins.atlassian.com Confluence as a Platform for Technical Documentation, by Sarah Maddox 34
- 36. Developing add-ons yourself Write a user macro: http://confluence.atlassian.com/display/DOC/Writing+User+Macros Develop a plugin: https://developer.atlassian.com/display/DOCS/Developing+with+the+Atlassian +Plugin+SDK Interact with the APIs: https://developer.atlassian.com/display/CONFDEV/Confluence+Developer+Do cumentation Confluence as a Platform for Technical Documentation, by Sarah Maddox 35
- 37. Getting hold of the book Wiki: https://wikitechcomm.onconfluence.com Amazon.com: http://www.amazon.com/ Confluence-Tech-Chocolate-Sarah-Maddox/dp/1937434001 Barnes & Noble: http://www.barnesandnoble.com/w/confluence-tech-comm-chocolate-sarah- maddox/1108812996?ean=9781937434007 XML Press: http://xmlpress.net/publications/chocolate/ Confluence as a Platform for Technical Documentation, by Sarah Maddox 36
Notas do Editor
- Speaker’s notes: Introductory slideWhen the webinar starts:Welcome everyone.Welcome the guys from K15t Software and Stepstone Technologies, who will be giving demos during the webinar.Explain the format of the webinar.Sarah’s introduction:I’m excited about this webinar, because it’s about an aspect of wikis that I’ve come to see as very important: the fact that wikis are extensible, versatile, and built to be so. As a result, there’s a community of enthusiastic developers and innovators who devote a good deal of time to extending wiki functionality. They challenge the wiki software owners, and keep the wiki at the forefront of web technology.I think that we technical communicators can use this characteristic of wiki technology to great advantage.
- Speaker’s notes: Overview of Sarah’s presentationThis is an overview of my section of the webinar.I’ll start off with an introduction to Confluence as an extensible platform.I’ll show you how I recently worked with a publishing team and a plugin development team to write and publish a book on a wiki. This is a good example of how we can take advantage of the extensibility of the wiki.Then we’ll broaden our view, to technical communicators in general and the sort of platform we need.We’ll see some specific examples of plugins and add-ons for Confluence, and we’ll discuss how we can contribute to wiki development and help ensure that it goes the way we want it to go.
- Speaker’s notes: Wiki as extensible platformConfluence is a wiki. In essence, this means that Confluence displays web pages with a magic edit button. Wikis have moved on since the early days, where editing a page was their main offering. Now they do a lot more. Even so, most people who use Confluence will see the web interface. They will read the wiki pages, edit or comment on the pages, and interact with the content in other ways.Looked at from another point of view, Confluence is also a configurable platform.Administrators can adjust the look and feel, and enable or disable parts of the functionality.But there’s more, and this is the crux of this webinar: 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.The Atlassian 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: Wiki as extensible platformWhat I'm proposing is that versatility and extensibility are strong points of a wiki, often not given enough emphasis when people are considering the choice of a tool.Also, perhaps people who already have a wiki are not as aware of these points as they could be. There’s an ecosystem of people around the wiki, offering development services as well as advisory services.
- Speaker’s notes: Wiki as extensible platform1) The Atlassian developers build the core Confluence features, and they also put significant effort into building and maintaining the hooks that make extensions possible.Plugin frameworkJava APIsRemote APIsOther innovative add-on points such as user macros, remote add-ons and SpeakEasy extensions.2) The community plugin developers (ecosystem) write add-ons and extensions.3) Experts write integrations and provide consultative services.
- Speaker’s notes: Wiki as extensible platformCustomers make use of the tools and services provided by all three.Let’s take a look at a specific example of extending the wiki: Writing and publishing a book.
- Speaker’s notes: Introducing the bookFirst, a quick overview of the book and what’s in it.(Discuss each point on the slide.)
- Speaker’s notes: Producing a book on a wikiTo produce and publish the book, I worked with Richard Hamilton at XML Press. Here’s a quick overview of how we went about it:I wrote the book on Confluence, and the editorial team joined me there too.We exported the content from Confluence to DocBook XML.The publisher pushed the DocBook through some XSLT conversions to produce a PDF file, which he then sent to the printers.The publisher is also in the process of converting the DocBook to Kindle and EPUB formats, for the ebook sales.
- Speaker’s notes: Developing the book on the wikiThe idea of writing the book on the wiki was immediately appealing.Dogfood: It was just cool to write a technical book on a wiki about writing technical documentation on a wiki. Meta!Location: Provided I had online access, I could pick up the writing anywhere, anytime.Diagrams: There was a neat diagram tool already available: Gliffy. In fact, the Gliffy team gave me a free licence. I didn’t need any proprietary drawing tools, and again I could do the work anywhere, anytime.Collaboration: (next slide)
- Speaker’s notes: Developing the book on the wikiCollaboration: Producing a book is a team effort right from the start.I wrote the content on the wiki. Entirely.The technical reviewers conducted their review on the wiki. We chatted via comments, and I updated the pages with the resulting feedback.The copy editor worked on the wiki pages, and I watched his updates using wiki watches, and tweaked the content further.The illustrator interacted with us there too, uploading his images and iterating through the designs until we were all happy.
- Speaker’s notes: Gliffy for diagramsIt 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 images.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 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 bend the wiki to our will!
- Speaker’s notes: Technical communicatorsMoving on from the use case of the book, let’s broaden the discussion to talk about technical communicators and a wiki.Technical communicators...
- Speaker’s notes: Technical communicatorsWe need a tool that can keep up with us.Out of the box, the core Confluence functionality gets us a fair way along the track.You will probably need to add plugins to tailor the wiki to your requirements.Each person works in a different environment, and has different requirements.Let’s look at some technical documentation requirements to see what the core Confluence functionality provides, and the plugins available to extend it:WorkflowLook and feelSingle source publishing
- Speaker’s notes: Workflow using core ConfluenceOut of the box, Confluence provides enough functionality to support a simple workflow:Draft, review, publish.It’s what we have been using at Atlassian for years!Draft:Create the page, and hide it with page restrictions. Use the page restrictions to make the page visible to the groups of people who should see it when in draft. In our case, we make draft pages visible to and editable by all Atlassian staff.Collaborate with SMEs and technical writing team to finalise the draft.Review:Extend the page restrictions if necessary.Allow reviewers to comment on and/or edit the page.Request reviews of the page.Collaborate to finalise the content.Publish:Remove the page restrictions.This workflow can be cumbersome when dealing with large volumes of content.The workflow is also inadequate in more restricted environments, where legislative and regulatory requirements dictate a more complex workflow.
- Speaker’s notes: Look and feel with core ConfluenceThemes provide the primary way of adjusting the look and feel of your Confluence site. A theme is a bit like a browser skin. It changes the colours, font styles, and backgrounds. A theme can also add new options to the wiki functionality.Out of the box, Confluence comes with three themes:DefaultEasy ReaderDocumentationThe screenshot shows the documentation theme, which provides:A pleasant, sober style suited to documentation.Configurable page header and footer.Configurable left-hand navigation panel.A few other bits and bobs.
- Speaker’s notes: Look and feel with core ConfluenceOut of the box, you can also adjust:CSSColour schemesSpace and site logosVelocity layoutsSite home page
- Speaker’s notes: Look and feel with theme pluginsIf you need more flexibility, you can add a theme plugin. Here are some examples.
- Speaker’s notes: Zen Foundation themeThe Atlassian Developers site uses the Zen Foundation theme. It’s highly configurable and flexible, and allows you to create a wiki site that feels like a website.Darryl Dukeof Stepstone Technologies will be giving a demo of the Zen theme later in this session.
- Speaker’s notes: Single source publishingTechnical communicators often need to import content into the wiki from other formats, and to export it out of the wiki into the formats that our customers can read.When pulling content into the wiki, we want to accept as many formats as possible. We need to get content out of the wiki into a standard, portable format. Four years ago, when I first became acquainted with a wiki, options were decidedly limited. Since then plugin developers have worked wonders. They have started building the technology that technical communicators get excited about.
- Speaker’s notes: Many, many more add-onsWe’ve looked at just three scenarios, and the add-ons available to cater for them. There are many many more add-ons. This slide shows some of the categories relevant to technical documentation. Search the Atlassian Plugin Exchange to see what’s available.
- Speaker’s notes: Confluence CLI by Bob SwiftThis is a special mention of an extremely useful tool developed by Bob Swift. It’s not a plugin, but rather a command line interface that uses the Confluence remote APIs. You can run it from your local PC. Just unzip it, give it the address of the Confluence server and a username/password to work with, and then pass it commands to update pages in bulk.I’ve used it in the past to delete a number of unwanted pages from our developer wiki.We’re also considering another use case that would incorporate the CLI into our regular processes, involving updating the documentation for product releases. If we do decide to do this, I’ll blog about it.
- Speaker’s notes: Plugins in Atlassian OnDemandThis is a quick note about Atlassian OnDemand, and the limitations of plugins and add-ons in this environment.Atlassian OnDemand is a service offering a hosted instance of Confluence and other Atlassian applications.Atlassian OnDemand comes with a set of pre-defined plugins. You cannot install new plugins or remove existing plugins. The commercial and bundled plugins listed on this slide are included with the service. You can enable, disable and configure them via your OnDemand administration console.What about the future of plugins and add-ons for Atlassian OnDemand? The Atlassian engineering team is working on the design for an infrastructure that will support add-ons better. They are working with add-on developers to get something ready as soon as possible. The current thinking is to provide a framework for remote applications to integrate with and interact with the applications in OnDemand. Stay tuned for information.
- Speaker’s notes: How the book deals with pluginsBefore we go on, I’d like to tell you how the book deals with plugins, add-ons and other tools.Each chapter of the book deals with a particular use case, such as exporting content, reusing content, and so on. The book describes the core wiki functionality for each use case. Where relevant, it gives details of the plugins and other tools that are useful too.At the end of every chapter is a list of plugins and tools that are relevant to the use cases covered in that chapter.Chapter 2 introduces plugins in general, what they are and who builds them. Chapter 4 describes planning your wiki and deciding whether you need to install plugins to get the functionality you need.Chapter 23 is all about driving wiki development. (Lead into next slide.)
- Speaker’s notes: Wiki as extensible platform(Repeat of earlier slide.)At the beginning of the presentation, we saw how customers make use of the core wiki functionality as well as the add-ons and extensions provided by the community and experts. As technical communicators...
- Speaker’s notes: Driving wiki developmentAs technical communicators, we are customers too.More than that, we can be drivers of wiki development. We have the skills, knowledge and passion. We know what we need, and we know a lot about what needs to happen to make the platform satisfy our requirements.We can work with the ecosystem to drive wiki development. Take advantage of the skilled and enthusiastic group of add-on developers, and let them take advantage of our knowledge and passion too.We can let Atlassian know what we need, by joining user groups, logging issues on the wiki, and joining discussion wherever we can.We can also do some development of our own.