Structured Wikis

Start presentation

Slide 1: Welcome

Structured (Enterprise) Wikis

Vicki Brown (vlb@cfcl.com)

Canta Forda Computer Laboratory

http://wiki.cfcl.com/Learn/StructuredWikis

Slide 2: Scenario

I get a call from a recruiter:

Recruiter: What content management systems have you used?

Me: I primarily use a wiki called TWiki...

Recruiter: Wikis aren't content management systems.

Me: The wikis that I use, are.

Recruiter: ???

Slide 3: Web Content Management Systems (1)

A structured enterprise wiki is more than an editing platform.

It's a web content management system:

A web content management system (WCMS) is a software system that provides website authoring, collaboration, and administration tools designed to allow users with little knowledge of web programming languages or markup languages to create and manage website content with relative ease.

A robust Web Content Management System provides the foundation for collaboration, offering users the ability to manage documents and output for multiple author editing and participation.
...

Slide 4: Web Content Management Systems (2)

...
Most systems use a content repository or a database to store page content, metadata, and other information assets that might be needed by the system.

A web content management system is used to control a dynamic collection of web material, including HTML documents, images, and other forms of media. A CMS facilitates document control, auditing, editing, and timeline management.

-- Web content management system (WP)

Slide 5: Web Content Management Systems (3)

Typical features:

  • Access control — registered users and user groups
  • Collaboration — content can be worked on by one or many users
  • Content syndication — RSS and Atom data feeds
  • Subscription — send email when updates are available
  • Easily editable — non-technical users can create and edit content
  • Scalable feature sets — plugins extend a site's functionality
  • Templates — standard look & feel can be applied to content
  • Workflow management — e.g. draft ==> edit ==> publication
  • Multilingual — display content in multiple languages
  • Versioning — revert to or reference a previous instance
  • ...

Slide 6: Wiki as Web CMS

  • What is a wiki?
  • Choices
  • Enterprise wikis
  • Structured wikis
  • TWiki and Foswiki
  • Features
    • Content Development
    • Macros
    • Extensions
    • Applications

  • Wiki App Use Case

  • Reference Examples
    • CSS Customization
    • JavaScript Customization
    • Macros (Variables)
    • Extensions (Plugins)

Slide 7: What is a Wiki?

A wiki is

  • a user-editable web site ...

  • that lets users write, place pictures, and post links ...

  • anywhere on any page ...

  • collaboratively ...

  • without special knowledge, applications, or server access

Slide 8: Wiki History

  • The word "wiki" was coined in 1994
    • For the first wiki program: WikiWikiWeb (WP)
    • Created by Ward Cunningham

  • Based on a Hawaiian word for "fast".

"I chose wiki-wiki as an alliterative substitute for 'quick'
and thereby avoided naming this stuff quick-web."

— Ward Cunningham

Slide 9: Ease of Use

  • No additional software to install on the user's computer:
    • All software is installed on the server
      and viewed through a web browser.

  • No need to learn HTML (use wiki markup codes instead).
    • However, if you know HTML, you can use it!

  • No waiting for a designated webmaster:
    • Be sure to check any local publication guidelines first!

  • No need to ask permission, in general, to edit content:
    • However, your local policies and processes may differ.

Slide 10: Choices: Simple to Powerful

Hundreds of "wiki engines" are available,
ranging from absurdly simple to extremely powerful!

See http://www.wikimatrix.org/ for a list
and to compare features.
wikimatrix.png

Slide 11: Enterprise Wikis

Suitable for use in corporations. Provide features companies expect.

  • Access control
  • Revision History
  • Separate areas (spaces, webs, ...) for different teams
  • HTML, CSS, JavaScript
  • Variables
  • Extensions (Plugins)
  • Email notification (subscribe to changes)
  • ...

ref: Wiki software (WP)

Slide 12: Enterprise Wikis

Many proprietary wikis market themselves as enterprise ready:
  • Confluence
  • Jive
  • SocialText
  • ...

Several Open Source wikis also offer enterprise features:
  • EXo_Platform
  • Foswiki, TWiki, XWiki
  • MediaWiki (and spin-offs)
  • ...

Slide 13: Structured Wikis

Structured wikis

  • Combine the benefits of a wiki and a database-backed application

  • Data is stored in forms (key/value stores) attached to pages

  • Support creation of small applications within the wiki

Structured data + Variables ==> Easy reporting, Improved workflow

Slide 14: Structured (Enterprise) Wikis

  • Structured data features built in
    • Foswiki, TWiki, XWiki

  • Plugin required
    • Confluence (additional cost)
    • MediaWiki (e.g. SMW)

Slide 15: My Favorite Wikis: TWiki and Foswiki

  • Open Source Structured Enterprise Wikis
  • Free to install and use (GNU GPL)
  • Freely available extensions (Perl plugins)
  • Global development and support community

Slide 16: Terminology

  • Web - a collaboration area, aka "space" or "namespace"
    Implemented as a directory on the server

  • Topic or page - a single URL
    Implemented as a text file on the server
    May include content from other files

Slide 17: Features — Documentation

  • Content Development
    • Markup language
    • WYSIWYG editor
    • More power:
      • HTML, CSS, JavaScript

  • Images and other attachments

Slide 18: Content Development (1)

Choose wiki markup (w/HTML) or an WYSIWYG editor.

Links can be written in CamelCase or enclosed in [[double brackets]].

Variables can be used for long and/or common strings.

Slide 19: Content Development (2)

Wiki Markup

WikiFormattingHelp.png  
 

Slide 20: Content Development (3)

If you need more power:

  • Full HTML tag set supported

  • CSS customization
    • per-topic, per-web, or site-wide
    • "Skins"

  • JavaScript supported

Slide 21: Customization

From default wiki Look & Feel to whatever you want!

ScreenShotBAAPTpage-1.png   ScreenShotBAAPTpage-2.png

Slide 22: Attachments

  • Arbitrary attachment types: Word, PDF, Images, ...

  • Images expand in place

  • Revision control for attachments
    (no need to name attached files with today's date)

Slide 23: Features — Power

  • Macros (aka Variables)
    • Simple or parameterized
    • User definable

  • Extensions (Plugins)
    • Extend the functionality of the wiki

  • Applications
    • Store data in forms.
    • Database-like access.

Slide 24: Macros

  • Text strings that expand into content whenever a topic is rendered for viewing.

  • Built in or user-created.

This topic, %TOPIC%, has revision info:  %REVINFO%.

This topic, StructuredWikis, has revision info: r17 - 19 Dec 2014 - 19:35:52 - Main.VickiBrown.

Slide 25: Extensions (Plugins)

  • Extend the functionality of the base wiki.
    • Extensions install their own macros.

  • Many plugins included with distribution
    • Hundreds more available for installation

  • Simple installation process
    • with a few exceptions
    • requires administrator privileges

Slide 26: Applications

  • Structured data

  • Combine the benefits of a Wiki with database search functionality.

  • Build small applications without backend coding.

Structured data + Extensions + Variables ==> Applications

Slide 27: Application Examples

  • Blogging
  • Status reports for teams
  • Team directory and contact manager
  • Project Tracker
  • Event tracker (Month and week calendars with an "add event" form)
  • Runbooks for Service Engineering
  • Document repository with dynamic indexing
  • ...

ref: Application Examples

Slide 28: Application Use Case

Document Repository

I was approached by our department's senior software architect to assist in refactoring their development standards documentation process.

The Engineering Standards team was responsible for creating, documenting, and monitoring development standards and their use across the organization. Each standard was developed by one or more people. Each draft standard would be reviewed by multiple people, then accepted and published. Over time, some standards were deprecated; however, all documentation was archived for historical purposes.

When the project reached me, there were approximately 50 standards documents in various stages. The current index of standards was a hand-edited tabular list which no longer matched the actual documentation. There was no standard for creating standards documentation.


Slide 29: Document Repository Overview

Before Application Creation

  • No standard for document creation or workflow

  • Documents created by copying and modifying an existing document.

  • New pages manually added to an index table.
    • Recently accepted documents manually marked as "New".
    • Older standards manually marked as deprecated.
    • Lack of standardization makes some table columns "brittle".

  • Not easy to search (e.g. "Show me only Mandatory Standards").

  • Much manual effort required. (Human error!)

Slide 30: Document Repository Overview

After Application Creation

  • New documents use a form to capture required metadata.

  • Template provides standardized "look" to pages.

  • Documents are dynamically indexed.
    • Standards marked as "New" NEW based on date comparison.

  • Easy to search (e.g. "Show me only Mandatory Standards").

  • Manual effort confined to writing the differentiated content.

Slide 31: Document Repository — Process

Before

  1. Open an existing document.
  2. Select and copy the content (don't change anything).
  3. Start a new document, pasting in copied content.
  4. Edit out what doesn't fit the new standard.
  5. Edit in new content.
  6. Try to include all required sections...
  7. Review and compare to other documents.
  8. Edit, repeating steps 4-7.

Slide 32: Document Repository — Process

After

  1. Enter required metadata into a form.
  2. (Template is copied automatically.)
  3. Add document-specific content to the resulting page.

Slide 33: Document Repository: Create New Document

After

Fill in a "New Standard" form with required data.

CreateNewDocument.png

Slide 34: Document Repository: Format

Before

  • No standardized look and feel.

  • Process:
    • Choose a "similar" document.
    • Edit to taste.
    • Don't accidentally change the "source" document!

Slide 35: Document Repository: Document Format

After

  • Standardized Look and Feel automatically applied using templates.

  • Process
    • Fill in a "New Standard" form with required data.
    • Click the button to automatically copy template.
    • Start editing unique content.

StandardLookAndFeel.png

Slide 36: Document Repository — Index

Before

  • Index table built by hand.
    • To change the information shown, rebuild the table.

  • NEW tag and deprecated information added by hand.

  • Patterns used for extracting contact names from documents are brittle and
    may break when content is edited.

Slide 37: Document Repository — Index

Before

It doesn't look bad...

Index_Before.png

Slide 38: Document Repository — Index

Before

But this is what they were editing by hand:

| *Name* | *Status* | *Date of Adoption* | *Area* | *PM Contact* | *Engineering Contact* | *Applies if...* | *To comply* |
| [[StdTracking][Defect Tracking: Bugzilla (bug.corp)]] | Mandatory | 01/Jun/2006 | Development Process | %SEARCH{"PM Contact" topic="StdTracking" regex="on" nonoise="on" format="$pattern(.*?PM\sContact\:\*\s*([^\n\r]+).*)"}% | %SEARCH{"Engineering Contact" topic="StdTracking" regex="on" nonoise="on" format="$pattern(.*?Engineering\sContact\:\*\s*([^\n\r]+).*)"}% | Always | Must use Bugzilla to track bugs |
| [[StdPkg][Packaging/Repository: yinst (dist)]] | Mandatory | 01/Jun/2006 | Development Process | %SEARCH{"PM Contact" topic="StdPkg" regex="on" nonoise="on" format="$pattern(.*?PM\sContact\:\*\s*([^\n\r]+).*)"}% | %SEARCH{"Engineering Contact" topic="StdPkg" regex="on" nonoise="on" format="$pattern(.*?Engineering\sContact\:\*\s*([^\n\r]+).*)"}% | Publishing or deploying  software | Must use packaging format and dist repository |
...

  • Are all entries here?
  • I sorted order?
  • What if you want to change columns?

Slide 39: Document Repository — Index

After

  • Table is built dynamically (no editing by hand).

  • Easy to add, remove, or re-order columns.

  • Index is searchable by column data.

  • Entries are always sorted.

Slide 40: Document Repository — Index

After

Index_After.png

Slide 41: Document Repository: "New" or "Deprecated*

Before

  • "New" and "Deprecated" tags added manually.

  • "New" must be removed manually, as well.

NEW Source Control: Subversion Mandatory 01/Mar/2009 Development Process ...
NEWAutomated Build Deprecated 01/Jun/2006 Development Process ...

What does it mean to be NEW and also deprecated?

Slide 42: Document Repository: "New" or "Deprecated*

After

  • "New" and "Deprecated" are calculated for each item,
    based on date comparison or metadata values.

  • Variables are set up once; the computer does the rest.

  • A different icon signifies "Deprecated".

Before

Same search options as for any page.

  • Wiki "page search"

  • "Find" in Browser

Search_before.png

After

Queries based on metadata (as entered into forms).

Search_after.png

Slide 45: Use Case: Questions?

hands_and_questions.jpg

Slide 46: Reference Examples

  • CSS Customization

  • JavaScript Customization

  • Macros

  • Plugins

Slide 47: JavaScript and CSS Customization

Example: Add color to table data, with highlighting based on cell content.
(Project managers love this!)

Table with status information:

TableData.png
Automatically highlight cells based on content:

TableDataColored.png

ref: tutorial (uses CSS and JavaScript)


Slide 48: Macros — Simple

Examples

%RED%Text%ENDCOLOR%
18 pre-defined colors. Add your own...
Text
Text, Text, Text
%DATE% 22 Sep 2017
%WIKINAME% WikiGuest
%TOPIC% StructuredWikis
%U%, %N%, %X%, ...
Multiple pre-defined shortcuts. Add your own...
UPDATED, NEW, ALERT!, ...

Slide 49: Macros — With Parameters

Some macros take parameters. Built-in only. Often used to drive Extensions.

%ICON{"name"}%
hundreds of pre-defined icons. Add your own...
%ICON{"book"}% %ICON{alert}%
%ICON{chart-bar}% %ICON{comments}%
%ICON{days}% %ICON{globe}%
Book alert chart-bar comments days globe
%SERVERTIME{"format"}% %SERVERTIME{"$hou:$min"}% 13:41
%SPACEOUT{"string"}% %SPACEOUT{"KumquatOverview"}% Kumquat Overview
%REVINFO{"format"}% %REVINFO{format="r$rev - $date - $wikiusername"}% r17 - 19 Dec 2014 - Main.VickiBrown

Slide 50: Macros — User Definable

Macros can be set for a topic, web, or site.

Users can set preferences via macros.

Some built-in macros are commonly redefined.

   * Set WEBBGCOLOR = #FFD8AA

   * Set EDITBOXHEIGHT = 40

   * Set ALLOWTOPICCHANGE = Main.AdminGroup

Slide 51: Macros — User Definable

Users can create their own macros:
   * Set CYAN = <font color="#3399ff">

   * Set Bookurl = http://www.amazon.com/dp/B00C7CC4JO

   * Set Prestitle = Structured Enterprise Wikis

And then use those variables in topics:

The title of this presentation is %Prestitle%.

The title of this presentation is Structured Enterprise Wikis.

Slide 52: Handy Documentation Macros

Aside from the ability to create and use variables (e.g. %Prestitle%) throughout your content, TWiki/Foswiki provide a number of handy built-in macros that make content development and management easier.

%TOC% — Automatic clickable tables of contents.

%INCLUDE% — Include content from another page in the wiki or from the WWW.

%SEARCH% — Search across topics or content and embed results in a topic.
Results can be formatted as desired.

...

Slide 53: Handy Documentation Macros: TOC

Automatic, clickable tables of contents, built from section headers.

Syntax

%TOC%

%TOC{"TopicName"}%

%TOC{"WebHome" web="Help"}%

%TOC{depth="3"}%

Example

TOC.png

Slide 54: Handy Documentation Macros: INCLUDE

Include content from another page in the wiki or from the WWW.

Syntax

%INCLUDE{"TopicName" parameters}%

%INCLUDE{"StructuredWikiExtras" section="include1"}%

Example

This text is included from the StructuredWikiExtras topic.

Search across topics or content; embed results in a topic.

Results can be formatted as desired.

Useful for creating automatic indexes.

Syntax

%SEARCH{"text" format}%

%SEARCH{"Web" scope="topic" limit="3"}%

Example

SearchScreenShot.png

Slide 56: Extensions — Just a Few Examples

  • Calendar
  • Comment
  • EditTable, Table
  • Slideshow
  • Spreadsheet
  • TreeBrowser, Tree
  • Twisty
  • ...

Slide 57: Calendar

Add a calendar to any topic.

Calendars are customizable and can contain events.

%CALENDAR%
Calendar1.png

%CALENDAR{month="12" year="2014" showweekdayheaders="1" weekstartsonmonday="1" 
eventbgcolor="pink" topic="StructuredWikiExtras"}%
Calendar3.png

Slide 58: Comment

Accept viewer input on a topic, from simple 1-line comments to surveys.
Both input (form) and output can be formatted as desired.

A target topic can be specified.
If not included, comments are added to the current topic.

%COMMENT%

%COMMENT{attributes}%

 

Slide 59: Comment

Comment format can be arbitrarily complex.

%COMMENT{type="spec"}%

CommentScreenShot.png

Slide 60: Tables

Easily display data in tabular form.

Use %TABLE% to specify formatting.

%TABLE{tableborder="4" tablebordercolor="red" dataalign="center" 
headerbg="pink" databg="#ffffcc,#f2f2f2"
sort="on" initsort="2"}%
| *Region:* | *Sales:* |
| Northeast |   320 |
| Northwest |   580 |
| Southeast |   210 |
| Southwest |   999 |


Region: Sales:Sorted ascending
Southeast 210
Northeast 320
Northwest 580
Southwest 999

Slide 61: Tables

If you don't want to change any of the default formatting, you can leave out the %TABLE% macro.

| *Region:* | *Sales:* |
| Northeast |   320 |
| Northwest |   580 |
| Southeast |   210 |
| Southwest |   999 |


Region: Sales:
Northeast 320
Northwest 580
Southeast 210
Southwest 999

Slide 62: Editable Tables

Edit tabular data through the browser.

%EDITTABLE{format="|text, 20|text, 20|"}%
| *Region:* | *Sales:* |
| Northeast |   320 |
| Northwest |   580 |
| Southeast |   210 |
| Southwest |  1000 |

EditTable_Tablemode.png

Slide 63: Editable Tables

EditTable_editmode.png

Slide 64: Slideshow

No need for Powerpoint. :-)

%SLIDESHOWSTART{template="Projects.SlidesTemplate"}%
---++ Slide Header
Content
...
%SLIDESHOWEND%

Slide 65: Spreadsheet (CALC)

Perform spreadsheet calculations, with or without tables.

Run formulas on numbers and strings.

%CALC{"formula"}%

%CALC{"$EVAL( (5 * 3) / 2 + 1.1 )"}%

%CALC{"$EXACT(foo, Foo)"}%

%CALC{"$FORMATTIME(0, $year/$month/$day GMT)"}%

%CALC{"$LISTITEM(2, Apple, Orange, Apple, Kiwi)"}%

8.6

0

1970/01/01 GMT

Orange

Slide 66: Spreadsheet (CALC)

Spreadsheet really shines with tabular data.

Region: Sales:
Northeast 320
Northwest 580
South 240
Europe 610
Asia 220
Total: 1970

The formula next to "Total" is

%CALC{"$SUM( $ABOVE() )"}%

Slide 67: TreeBrowser

TreeBrowser renders a bulleted or numbered list as a collapsible / expandable
tree of nodes.

Use TreeBrowser with TOC to provide an expandable table of contents.

%TREEBROWSER{"forum" title="Contents" }%
%TOC{"WebHome" web="Help"}%

Contents_closed.png

Contents_open.png

Slide 68: Tree

Tree renders topics' parent-child relationships as a hierarchical tree view.

Add TreeBrowser for expand / collapse functionality.
%TREEBROWSER{"forum" title="WikiTut topics" openTo="1" }%
%TREEVIEW{web="Help" formatting="outline" format="* [$topic]"  levelprefix="   " excludetopic="Web*"}% 

TopicTree_closed.png

Slide 69: Twisty

Hide and show content.

%TWISTY{_parameters_}%
Content
%ENDTWISTY%


As I was going up the stair,
I met a man who wasn't there.
He wasn't there again, today.
I really wish he'd go away!


Slide 70: Questions

Questions.jpg

Slide 71: More Information

Find more information about TWiki, Foswiki, and wiki apps:

Slide 72: Contact

-- Main.VickiBrown - 16 Dec 2014
Topic revision: r17 - 19 Dec 2014, VickiBrown
This site is powered by FoswikiCopyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding CFCL Wiki? Send feedback