Developing and Delivering Documentation in a Wiki

1. Developing and Delivering Documentation in a Wiki Dee Elling, Senior Manager Information Engineering

2. 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

3. 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

4. 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

5. 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!

6. The Hype Curve

7. Topics API Examples 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?

8. 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

9. Topics API Examples First Round Examples Wiki API Wiki (x4) Import Topics Wiki (x4) WikiFarm XML Content Sources Export Output Formats MS Help2 (x4) and Installer

10. 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 Which wiki? Mediawiki

11. Out-of-the-Box CMS Revision tracking History User management Statistics Out-of-the-Box and Custom Development • Custom Development • Import/export scripts get content in and out – Python, JSON • Skins – CSS • Preferences - Javascript

12. 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 Skills to Acquire

13. 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 Iterations

14. Help2 and link to wiki page

15. Wiki page in Help2 viewer

16. TOC in Help vs. wiki TOC Wiki page-level TOC Similar TOCs

17. Discussion/Talk/Comments about a topic page Customer comments Writer response

18. Revision history

19. 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 Writer experiences

20. 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…

21. 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 Mind-leaps PERSONAL CONNECTION is the thing • NYT online – 11 comment moderators • It is the most rewarding perk of writing 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

22. 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 Next few leaps Deal better with translations More content = more costs? Is there a better way… watch what Google does Deal with versioning Technical and process issues Give back to the Mediawiki community Donate our Help generation scripts The Great Unknown Expect the unexpected

23. 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 Hindsight… Translation issues Almost killed the project timing too tight for L10N It takes experienced skills Underestimated technical complexity Not “just XML and LAMP”

24. 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 ------------------------------>

25. 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

26. Writer Workflow

27. Browser view

28. Editing wikitext

29. French version