Embed Size (px)
DESCRIPTION
The presentation makes the case that it is better to create a separate Confluence wiki page for each topic than to create copies of that topic in multiple guides. It presents a sample structure for a user's guide created in Confluence that makes use of local content but also macros that pull in content from elsewhere, allowing you to use the same wiki topic in multiple guides.
Citation preview
Don’t Duplicate It, Include It!
Carolyn Kelley Klingerhttp://www.slideshare.net/cklinger500/dont-duplicate-include
2
What is a Wiki? A website that allows collaborative
editing of its content and structure by its users
Don’t Duplicate It, Include It!@cklinger #stc14
3
My Confluence Bias
@cklinger #stc14 Don’t Duplicate It, Include It!
4
Wikis are Perfect for DocumentationOne guide or one topic per wiki page Content is always currentEveryone can see changesCan roll back to previous versionsCan search content and attachmentsCan restrict public viewing/editing of a
page while it is in draft
Don’t Duplicate It, Include It!@cklinger #stc14
5
Reuse vs. DuplicationReuse
Duplication
Guide 1, Wiki Page
AGuide 2, {Include Page|Wiki Page A}
Guide 1, Wiki Page
A
Guide 2, Wiki Page
A
Don’t Duplicate It, Include It!@cklinger #stc14
6
Why Reuse Wiki Content?You want…
Quality that results from eliminating human error
Accessibility of non-text contentConsistency of content and structure
You might need to save space
Don’t Duplicate It, Include It!@cklinger #stc14
7
What’s Wrong with Duplication?Version control issuesHave to edit in multiple placesHuman error duplicates itself as wellIncreased time and effort
Don’t Duplicate It, Include It!@cklinger #stc14
8
How to Make a Wiki Guide1. Create a new wiki page as a guide
shell.2. Create an inclusion library at the wiki
root.3. Write each topic as its own wiki page.4. In the guide shell, include topics.
Don’t Duplicate It, Include It!@cklinger #stc14
9
Simple Guide Shell
@cklinger #stc14 Don’t Duplicate It, Include It!
10
Guide Shell with Chapters
@cklinger #stc14 Don’t Duplicate It, Include It!
Wiki editor view
Published page view
11
Keep Inclusions OrganizedStore Inclusions at Wiki Root
LevelEach Version Has Unique
Content
@cklinger #stc14 Don’t Duplicate It, Include It!
12
Same Wiki Page, Two Versions
Don’t Duplicate It, Include It!@cklinger #stc14
13
Common MacrosPage InformationChildren DisplayInclude PageTipPanelTable of Contents
Don’t Duplicate It, Include It!@cklinger #stc14
14
Pull In Content with Macros1. Source Page
2. Tip Macro and Include Page Macro in C0nfluence Editor
@cklinger #stc14 Don’t Duplicate It, Include It!
3. Published Content
15
Wiki Documentation Set
Don’t Duplicate It, Include It!@cklinger #stc14
Don’t Duplicate It, Include It! 16
Published Wiki Guide
@cklinger #stc14
17
Thank You!
@cklinger #stc14 Don’t Duplicate It, Include It!
Image Source: http://learningwithwikis.wikispaces.com
