Developing and Delivering Documentation in a Wiki

Dee Elling, Senior Manager Information Engineering

Topics

• Trends in Communications

• Legacy Tech Doc and Scaling Down

• The Hype Curve

• Technical considerations and the bleeding edge

• Iterations and screenshots

• Writer experiences

• Customer experiences

• Analytics

• Resources

http://docwiki.embarcadero.com

Trends in Communication

• “Here comes everybody” – the reader/customer/partner using social media

• Customers are active on blogs and forums

• Partners using wikis for their docs

• Writers need more help from teammates – developers, QA, product management

• Many brains equals better information• Long tail

• Institutional vs. collaborative information

• People are social learners – learn better together, in person and online

• Clay Shirkey, Stewart Mader

Trends in Technical Communication

• The way we teach/learn/do is changing• Info overload, learn to forget

• Learn-on-demand

• The lecture becomes a conversation

• The model of the expert who knows everything has

morphed into groups who each know a bit of it• crowdsourcing

• Top-down vs. lateral authority

• Your customers often know more about a product than

your tech writers do

• Ann Gentle’s book and blog

• “Move over DITA, here comes Chaos” Alan J. Porter

• “Wiki Use for Product Documentation” Jeff Gardiner

• Podcasting blog by Tom Johnson

Legacy Doc and Scaling Down

• Old software never goes away… • It just gets more complicated

• With fewer resources

• To meet existing high expectations

• RAD Studio (Turbo Pascal, Delphi, C++Builder)• Oldest components and users go back 20+ years

• Vocal, knowledgeable established user base

• Large and tangled API – ~60,000 files

• Topics that used to be book chapters – ~5,000 files

• 4 languages - 4 x (60,000 + 5,000)

• FrameMaker content converted to XML, proto-DITA in ~2005

• Homegrown scripts that worked pretty well and were evolving

• Layoffs, lost knowledge

• Engineering stepped in and implemented a quick fix ~2007

• New staff later found that the quick fix was not sustainable and had serious quality problems

• What to do? Wiki!

The Hype Curve

The bleeding edge, then and now

• XML saves translation and formatting costs • No question!

• Complexity adds other costs• Expensive, specialized knowledge for tools and processes

• Authoring tools are controversial

• Authoring remains the sole domain of the trained tech writer (“institutional information”)

• Need expensive content management systems to make it really work

• Trend is towards openness and loose structures• “Knowledge management” practices based on enforced structures and processes often fail

• Developers do use tools that have immediate results and “geek appeal”

• People prefer folksonomies (tag clouds) rather than predefined taxonomies

• Structured (machine-oriented) vs. unstructured (brain-oriented) content

• Findability – search is the #1 user interface; pre-arranged TOCs and indexes are secondary

• What kind of structure do we really need, for this, now?

Topics

Examples API

Technical considerations

• Originally wanted to keep all content in XML• But no XML wiki system

• Spent a lot of time trying to “round-trip” XML->Wiki->XML• Structured vs. unstructured

• “round-trip” probably requires a CMS

• And a wiki is a type of CMS

• So do we really need the content to be in XML?

• Translations! Cost more

• But the wiki could be a manageable CMS

• And we could script the transformation from wiki to Help2 (secret: it’s all

HTML anyways)

• And we could script the translation “diffs” to hand off to vendors

First Round

XMLContentSources

Import

WikiFarm

Export

TopicsWiki (x4)

API Wiki (x4)Examples

Wiki

MS Help2 (x4) and Installer

OutputFormats

Topics

Examples API

Which wiki? Mediawiki

•Top requirements• Scriptable – to get content in and out

• Easy to use – for writers/customers

• Multiple user roles and permission levels

• Stable

• Fast

• Internationalized

• Cheap

• Uses industry standards

• XML, HTML

• PHP, Python, MySQL

• Versioning

Out-of-the-Box and Custom Development

•Out-of-the-Box• CMS

• Revision tracking History

• User management

• Statistics

•Custom Development• Import/export scripts get

content in and out – Python,

JSON

• Skins – CSS

• Preferences - Javascript

Skills to Acquire

• New: Webmaster/Web Developer• LAMP stack plus Python, XML, JSON

• System administration

• Web CSS/HTML/Javascript

• New: Web Monitors “WikiGardeners”• Set up RSS feeds to monitor for updates

• Acknowledge and thank commenters/contributors

• Route change requests

• Make direct immediate edits

• Alert L10N or other teams as needed

• Changed: Writers and Editors• Learn wikimarkup or other editor

• New workflow

• New “visibility” to the public and each other

• Changed: Document Architects/Planners

• “WikiGardeners” prune/shape wiki pages

• Incorporate wiki into planning

Iterations

• Phase 1: Test installs and informal evaluations

• Phase 2: Beta only – writing, adoption• MindTouch Dekiwiki

• Writers and beta customers wrote new content on wiki

• Writers later merged into XML and generated Help2

• Phase 3: Full release using Mediawiki and Help2• Content converted

• Lots of bug fixes and tweeks to conversion processes

• Writers, developers, translators, and beta customers worked on wiki

• Help2 generated from wiki

• Phase 4: Refinements• Integration w/Compiler-generated doc

• PDF plugin for user-generated PDF

• Generate CHM and/or Help3 and/or Adobe AIR Help format

• Phase 5: Improve L10N costs• Workflow integration w/Jira

Help2 and link to wiki page

Wiki page in Help2 viewer

TOC in Help vs. wiki TOC

Wiki page-level TOC

Similar TOCs

Discussion/Talk/Comments about a topic page

Customer comments

Writerresponse

Revision history

Writer experiences

A Ha! Moments

• Much faster to write in wikitext than in

XML (Epic, Oxygen)

• Liked to see changes from colleagues

overseas, every morning

• Like responding to customers who ask

good questions – build relationships

Oh @!x Moments

• System problems – slowness

• Conversions gone awry• Special characters

• Capitalizations

• International character sets

Customer experiences

• “The help layout is better…” – forum

• “…the biggest enhancement in this release is the Help System” – blogger

• Regressions… we took our hits on the Help2• inability to get F1 help working properly in time for release resulted in a lot of complaints

• Missing graphics that are now part of the GUI and not linked into/out of the help yet

• “But…. better a new system with potential than an old one that will never work”

• A bit of a mixed bag on our wiki usage policies• Some don’t want to be screened – want instant, anonymous permissions

• Some don’t want to do “what they’ve paid for already”

• About 10% of Beta account holders made comments• With no real “marketing” on our part, just the docs

• About what I expected…

Mind-leaps

The wiki is ALWAYS LIVE

• No downtime, no static staging

• Control with page/user permissions

“Change in Equilibrium” from

institutional infrastructures to

cooperative infrastructures

• ….”This is superdistribution — content

moving from friend to friend through

the social network, far from the original

source of the story. Superdistribution…

matters so much, in fact, that we will

routinely prefer a shareable amateur

source to a professional source that

requires us to keep the content a

secret on pain of lawsuit. –Clay

Shirkey

Chaos is scary but not always bad

• Think without the box

It’s a Good Thing we’re “Agile”

• Innovation/iteration built into culture

• “Replace planning with coordination” - Shirkey

PERSONAL CONNECTION is the thing

• NYT online – 11 comment moderators

• It is the most rewarding perk of writing

Next few leaps

More VISUAL content

Even without

translations, you can

understand a lot with

pictures and video

Integrate more with other websites

Marketing and community sites, SEO

Give back to the Mediawiki community

Donate our Help generation scripts

Deal better with translations

More content = more costs? Is there a better way… watch what Google does

Deal with

versioning

Technical and

process issues

The Great Unknown

Expect the unexpected

Hindsight…

It takes more time

Underestimated everything

More internal “marketing” and

incentives to get people going

Lots of internal skepticism

People think anything new is just more

work for them…

Overcome that to get more internal

participation

Show how moving the conversations

from internal-only to internal and

external is helpful and feels good

Do it organically over time… relationships

cannot be forced

Translation issues

Almost killed the project

timing too tight for L10N

It takes experienced skills

Underestimated technical

complexity

Not “just XML and LAMP”

Analytics

• Analytics.google.com

• Jan –Feb –Mar 2010

• 82,270 unique visitors• Averaging 3.3 pageviews per visit, total 434,151 pageviews

• For almost 3 minutes each visit

• 58% new visitors

• 72% referred by google search

• From Japan, Germany, US

• Mediawiki statistics ------------------------------>

Tools and resources

• Sarah Maddox, tech writer at Attlassian and her blog at

http://ffeathers.wordpress.com/2009/09/14/getting-content-into-and-out-of-wikis/

• Ann Gentle, tech writer Conversation and Community and her blog at

http://justwriteclick.com/

• Clay Shirkey, NYU professor, internet guru, and former tech writer, his

blog at http://www.shirky.com/weblog/ and his videos; in particular his

2005 TED talk on institutions vs collaboration

• Stewart Mader, technology adoption evangelist at http://www.ikiw.org/

• “Move Over DITA, Chaos is Coming” Alan J. Porter

• http://webworks.com/Info/Wiki_Publishing/ Webworks

Writer Workflow

AttendSCRUMs

UpdateJira Tasks

- plans- notes

Request Editsand Reviews

Write Draftson beta wiki

Update Drafts

Hand off toL10N - Jira

Done?

Mark wiki pagesas complete for

help release

Monitor existingsubject matter on

wiki

Any changesto include?

yes

no

yes

no

Ongoing ActivitiesIndividual Subject Matter-related Activities

(Jira Task)

Writer Workflows

Browser view

Editing wikitext

French version