A Scriptorium webinar about technical communication, collaboration and Confluence wiki. This slide deck includes screenshots of the parts of the demo that were live on the wiki during the presentation.
WordPress Websites for Engineers: Elevate Your Brand
Collaboration: A hands-on demo using Confluence wiki
1. Collaboration: A hands-on demo
using Confluence wiki
Scriptorium webcast
26/27 April 2012
Collaboration using Confluence wiki, by Sarah Maddox Slide 1
1
2. Confluence, Tech Comm, Chocolate
A wiki as platform extraordinaire for technical communication
Introducing Sarah’s new book
Wikis and technical documentation
Agile environments
Social media
Crowd sourcing
Driving wiki development
And more
wikitechcomm.onconfluence.com
Collaboration using Confluence wiki, by Sarah Maddox Slide 2
2
3. A documentation wiki
http://confluence.atlassian.com/display/DOC Demo
Collaboration using Confluence wiki, by Sarah Maddox Slide 3
3
4. A developer documentation wiki
https://developer.atlassian.com/ Demo
Collaboration using Confluence wiki, by Sarah Maddox Slide 4
4
5. Introducing Donna Dark
Technical communicator extraordinaire
at Dangerous Liaisons
I’m Donna and I’m
everybody’s hero
Collaboration using Confluence wiki, by Sarah Maddox Slide 5
5
6. What we will cover
Collaboration, and why it’s a Good Thing
Introduction to wikis and Confluence
Creating a technical communication space
Collaboration tools
Wiki plugins and add-ons
A “how to”, not a
showcase of features
Collaboration using Confluence wiki, by Sarah Maddox Slide 6
6
7. Collaboration – a world of opportunity
Developers
Product
managers
SMEs
Support
engineers
Customers
Collaboration using Confluence wiki, by Sarah Maddox Slide 7
7
10. Introducing the wiki
With a wiki, you can
edit a web page in
A wiki your browser
Confluence and other brands
The dashboard
Spaces
Pages
Collaboration using Confluence wiki, by Sarah Maddox Slide 10
10
11. Confluence dashboard
Welcome message Recent activity Demo
Collaboration using Confluence wiki, by Sarah Maddox Slide 11
11
12. Wiki spaces and pages
Demo
A hierarchical
page structure
in a space A page
A list of spaces on
my Confluence
dashboard
Collaboration using Confluence wiki, by Sarah Maddox Slide 12
12
13. Division of content into spaces
Per manual? One of
Dangerous
Per product? Liaison’s
products
Per product version?
Killing Me Softly A space
SOFT010 SOFT011 SOFT020
Collaboration using Confluence wiki, by Sarah Maddox Slide 13
13
14. Building a documentation space
Add the SOFT010 space
Let’s get
Theme cracking
Permissions
Design the home page
Wiki editor
Build a skeleton table of contents
Add the key pages 14
Move and order pages
Collaboration using Confluence wiki, by Sarah Maddox Slide 14
14
15. Adding your space (1)
Demo
Adding a
space to
Confluence
You can change the
permissions at any time
Collaboration using Confluence wiki, by Sarah Maddox Slide 15
15
16. Adding your space (2)
Demo
Choose the
Documentation
theme
You can also change
the theme at any time
Collaboration using Confluence wiki, by Sarah Maddox Slide 16
16
17. Setting the permissions Type of access
Demo
Groups
Individuals
Anonymous
users
Collaboration using Confluence wiki, by Sarah Maddox Slide 17
17
18. Designing a space’s home page
The default home page
Demo
The default content is
pretty ordinary, really
Collaboration using Confluence wiki, by Sarah Maddox Slide 18
18
19. Our new home page
Collaboration using Confluence wiki, by Sarah Maddox Slide 19
19
20. Designing a space’s home page
Demo
Our new
home page
Collaboration using Confluence wiki, by Sarah Maddox Slide 20
20
21. Adding a skeleton TOC
Demo
The table of
contents forms as
you add the pages
Collaboration using Confluence wiki, by Sarah Maddox Slide 21
21
22. Collaboration tools
Permissions
Sharing a page via email
@mentions
Notifications
RSS feeds
Let’s look at the
basic workflow
Collaboration using Confluence wiki, by Sarah Maddox Slide 22
22
24. Monitoring updates
Watch a page or space
Set your notification options
Use RSS feeds
I need to stay on top of
the news but avoid
information overload
Collaboration using Confluence wiki, by Sarah Maddox Slide 24
24
25. Watching a page
Choose “Tools” > “Watch”
Collaboration using Confluence wiki, by Sarah Maddox Slide 25
25
26. Watching a space
Choose “Browse” > “Advanced”
> “Start watching this space”
Collaboration using Confluence wiki, by Sarah Maddox Slide 26
26
27. Setting your notification options
Choose the type of
content you want to
know about
Choose the format of
the notifications
Collaboration using Confluence wiki, by Sarah Maddox Slide 27
27
28. Setting your notification options
?? Haven’t you seen
enough of my profile?
Collaboration using Confluence wiki, by Sarah Maddox Slide 28
28
29. Setting your notification options
Demo
Collaboration using Confluence wiki, by Sarah Maddox Slide 29
29
30. Building an RSS feed Choose
“Browse” > “Feed Builder”
Building an
RSS feed in
Confluence
Collaboration using Confluence wiki, by Sarah Maddox Slide 30
30
31. Collaboration in action
Add a draft page: Release notes
Set permissions ready for review
Share page
Publish the page
Collaboration using Confluence wiki, by Sarah Maddox Slide 31
31
32. Draft page – release notes
Demo
Lock indicates
page restrictions
Collaboration using Confluence wiki, by Sarah Maddox Slide 32
32
33. Ready for review
Demo
Broaden the
page restrictions Share the page
Collaboration using Confluence wiki, by Sarah Maddox Slide 33
33
34. The dashboard activity stream
Demo
Collaboration using Confluence wiki, by Sarah Maddox Slide 34
34
35. Wiki plugins and add-ons
Collaboration using Confluence wiki, by Sarah Maddox Slide 35
35
36. 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
Collaboration using Confluence wiki, by Sarah Maddox Slide 36
36
37. Many, many more add-ons
Exporting and importing content to various formats
Look and feel (themes)
Content reuse
Metadata
Templates
Diagrams and mockups
Social media integration
Website and application integration
You name it plugins.atlassian.com
Collaboration using Confluence wiki, by Sarah Maddox Slide 37
37
38. The magic of collaboration
Collaboration using Confluence wiki, by Sarah Maddox Slide 38
38
42. Contacting me
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/
Collaboration using Confluence wiki, by Sarah Maddox Slide 42
42
43. Taking your own wiki for a spin
Download Confluence or try it online:
http://www.atlassian.com/software/confluence/try
Licensing:
Evaluation for 30 days
Free for non-profit and open source organisations
$10 for a 10-user licence (proceeds go to “Room to Read”)
Commercial licences based on number of users
For this demo I used Confluence 4.2
installed locally on Windows 7.
My browsers are Firefox and Chrome.
Collaboration using Confluence wiki, by Sarah Maddox Slide 43
43
44. References
Confluence wiki
Website: http://www.atlassian.com/software/confluence/
Software for technical documentation:
http://www.atlassian.com/documentation-technical-writing-
software/overview
Documentation: http://confluence.atlassian.com/display/DOC/
Plugins: https://plugins.atlassian.com/search/by/confluence
Collaboration using Confluence wiki, by Sarah Maddox Slide 44
44
Notes de l'éditeur
Speaker’s notes: IntroductionWelcome, everyone, to this webinar about collaboration, technical documentation and Confluence wiki. I’m Sarah Maddox, a technical writer at Atlassian. I’ve spent the last fifteen years as a technical communicator, and almost 5 of those years have been on a wiki. I’m a self-confessed wiki hugger. Thank you so much to Sarah O’Keefe for inviting me to present a webinar for Scriptorium. It’s an honour and a pleasure to be here. And thanks to everyone who is attending.Collaboration is central to a technical writer's role. It takes the form ofPeer review by other technical writersInput from subject matter expertsFeedback from readersAll these provide valuable content throughout the life of a document. Collaboration is what makes our documentation correct and useful. It is how we deliver targeted information to our customers.Wikis are built for collaboration. So that’s why I want to show you one today.Before we dive into the wiki, I’d like to tell you a bit about my new book... [Link to next slide.]
Speaker’s notes: A documentation wikiAddresses:Confluence documentation: http://confluence.atlassian.com/display/DOC/Confluence+Documentation+HomeJIRA documentation: http://confluence.atlassian.com/display/JIRA/JIRA+Documentation+HomeThe Atlassian product documentation uses the Documentation theme, which is shipped with Confluence. This wiki contains the documentation for a number of products, including Confluence itself.This is the home page of the Confluence documentation.I’m using Firefox as my browser. The wiki pages are displayed as HTML in your web browser.DemoA very quick run-through of the following pages:Home page of Confluence documentation.Left-hand navigation panel.Confluence User’s Guide.Home page of JIRA documentation.OK, so that looks very much like a wiki. How about this... [Go to developers wiki in Firefox.]
Speaker’s notes: A developer documentation wikiAnd now for something completely different. At first glance, this doesn’t look like a wiki. But it’s Confluence, with a different theme, or skin.The Atlassian Developers site uses the Zen Foundation theme. This theme is highly configurable and flexible, and allows you to create a wiki site that feels like a website.DemoHome page.Top navigation bar.Docs page.Left-hand navigation bar.Atlassian MarketplaceNewsNow let’s get to know the hero of this webinar: Donna Dark. [Link to next slide.]
Speaker’s notes: Life of a document up to publicationThe traditional workflow for a document is this:Write the draftGet it reviewedPublish the final versionLater in the presentation, we will discuss how to handle this workflow on Confluence.For now, let’s look at the life of a document in another way... [Link to next slide.]
Speaker’s notes: The real life of a documentThe life of a document continues after publication.In fact, if you asked the document, it would probably say life has only just started at publication.There’s a new buzz word in town: “Continuous publication”.We live in a world of continuous publication. The first version of the document goes out when the product is released. That’s when real people start using the product. Pretty soon after the release, customers find things that the technical writers and the engineers never dreamed of. The documentation needs updating.The support engineers think up a workaround for a bug. The documentation needs updating.The engineers release a bug-fix version. The documentation needs updating.And so on.In an environment of continuous publication, it’s not practical to expect the technical writers to do all the updates. Instead, support engineers, product managers, developers, even customers will be able to make useful contributions to the documentation.It remains essential that the technical writers have the tools to manage the resulting updates.Enter the wiki. [Link to next slide.]
Speaker’s notes: Workflow using core ConfluenceThis is the slide I showed you earlier, about the initial workflow of getting a page to publication.Out 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. A page restriction is a type of permission in Confluence.Collaborate with SMEs and the technical writing team to finalise the draft.Review:Extend the page restrictions if necessary, to allow more people to see the page.Allow reviewers to comment on and/or edit the page.Request reviews of the page, using @mentions or the share functionality.Collaborate to finalise the content.Publish:Remove the page restrictions. When you do that, everyone who has permission to see the content of the space will be able to see the page.So, we’re planning to let a number of people update the page. How can we manage the updates? [Link to next slide.]
Speaker’s notes: Collaboration in actionLet’s put what we’ve learned into practice. [Talk through the slide.][Go to my Confluence site and add the release notes page.]
Speaker’s notes: Release notesThis is the page of release notes that we will add.Notice that we set the page restrictions immediately, so that only the technical writers can see the page.Demo:Page title: “KMS release notes”Content: See text file.Page restrictions: Technical-communicatorsPoint out the lock icon after saving the page.
Speaker’s notes: Ready for reviewDemo:Adjust the page restrictions: Technical-communicators and dl-staffShare the page with Damien.“Damien receives an email message, containing a link to the page. He will come to the wiki to do the review.”Swap to Chrome and log in as Damien.Change spelling and add a full stop.Add a comment – “Hey @Donna, great page. I’ve finished my review.”“Donna sees the notifications come into her email inbox.”Go back to Firefox window.“She doesn’t like the new full stop, so she removes that. She’s happy enough with the spelling changes.”Remove Damien’s comment.Publish the page.[Go back to the dashboard and see the activity stream.]
Speaker’s notes – The dashboard activity streamWe can see what Donna and Damien have been up to. It looks pretty cool.
Speaker’s notes: Wiki plugins and add-onsConfluence 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.Let’s look at some add-ons that are relevant to what we’ve discussed so far.
Speaker’s notes: Add-ons for enhanced workflowThe simple workflow we’ve just seen works well, but it iscumbersome and time-consuming when you’re 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.The plugins shown on this screen add sophisticated workflow to Confluence.[Talk through what’s on the slide.]
Speaker’s notes: Many, many more add-onsThere 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: The magic of collaborationLet’s assess what we’ve seen in this session. A wiki gives us: Power to control who can see and do what, via permissions.Power to see who is doing what, via notifications and RSS feeds.Ability to have SMEs updating the content directly, reducing the pressure on a small technical writing team.More, there’s thePracticality of having a single, central location that people update.The ease of a rich-texteditor that business users can use.Collaboration does not end at publication. We sneaked a look at what life is really like for a page.A wiki is an extensible platform. We can install add-ons, work with plugin developers to get what we need, and even try our hand at plugin development ourselves.In closing:Where I am now, collaboration is just the way things are. It’s accepted as the baseline for every document we create.I’d find it hard to go back to an environment where that’s not the case.Hey look, it’s a photo opportunity: Donna’s smiling.