developing and delivering documentation in a wiki dee elling, senior manager information engineering
Post on 19-Dec-2015
241 Views
Preview:
TRANSCRIPT
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 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
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
top related