LavaCon 2011: Why I left my CMS! and how I did it

Why I left my CMS! …and how I did itLavaCon ConferenceNovember 16, 2011 Mary Connor

Presenter Mary Connor  Documentation Architect, Advanced Solutions International  mconnor@advsol.com  www.cleverhamster.com (will post write-up)

Why Agile? Survival: Waterfall was drowning us. Literally.

Which flavor of “Agile”?  bullpens, no phones  Team = PO, SM, 3 dev, 2 QA, 1 BA, 1 TW  2-week sprints: planning, product backlog, capacity, acceptance criteria  SCRUM stand-ups  Review, retrospective

How do we collaborate? Ventrilo and Skype Mitel, video conferencing Yahoo IM Typewith.me and Google Wave Campfire, for team discussion Drupal: blogs, wikis, and forums BBFlashback videos Cacoo, for collaborative diagrams

How does Agile affect docs? Full pigs (committed to teams) No lagging! Docs are part of Definition of Done; incomplete doc tasks block the team Continuous, automated builds Integration and review limited to final regression sprints

So, why give up our CMS? People reasons Process reasons Tool reasons

People Reasons House Rule: cross-functional generalists  All are “Product Developers”  Everyone can and should write Info Dev lost half its writers No new writer hires likely (ever?)

Process Reasons New authoring outside of CMS! 1. Web part docs 2. Web services (API) docs Goals unmet by AuthorIT  Continuous Integration builds  All source files in Visual Studio

Tool Reasons AuthorIT licensing Ease of use Forced migration looming (v4 > v5)

Why not go straight to wiki? Confluence  Costs, complexity, scale  Conflict: IE/Win (ASPX) vs. Java Mediawiki  Can’t publish required outputs  Can’t secure content and access Drupal (as wiki)  Huge migration, v4 to v7  Need coder for complex reqs

Why Doc-To-Help? Single-sourcing across targets and sources: HTML, XHTML, DOCX One strategy for user and API docs Team features: integration with TFS, SharePoint; familiar, easy editors Command-line builds, build scheduler Able to handle ASI’s immense builds Affordability

Ready for heresy?

Our earlier crisis, B.C. Pre-CMS, Word-based source Doc and Training diverging horribly President’s command: Thou shalt merge Documentation and Training depts Goal: Single-source across silos

Turned to Instructional Design Tried topic-based writing  poor results  lacking clear context and audience Studying instructional design, found Reusable Learning Objects (RLO)  Rather than topic-based content, do objective-based content unit  Goal: reuse unit across courses, platforms

Our “learning object” content unit Learning unit, for specific user type 1. Objectives * 2. Feature at-a-glance $ 3. Concepts 4. Processes, procedures 5. Reference + 6. Hands-on exercises * • * training only • $ share with marketing • + documentation only

Just enough granularity: Score! In CMS, sub-book = RLO Arrange into publishing books, for reuse needs Sub-book embodies our metadata: • Audience • License level • Purpose (e.g., marketing) • Target (e.g., manual only) • Subject

You heard me: Don„t reuse topics! Migrating to CMS, I outlawed “topic- based authoring” in favor of “sub-books” (RLOs) Rule 1: Reuse books across the library, but avoid reusing topics across books Rule 2: If you must, flag those reused topics (asterisk in topic description) to warn others

Migrating from a CCMS1. Unraveled reuse so each object exports only once (single-sourcing)2. Exposed hidden notes/history3. Optimized templates for D2H import4. Macros to post-process5. Automated migration so we could iterate

Our Doc-To-Help Configuration D2H installed on test + build machines Source editable on any TFS machine, by every Agile team member D2H builds from TFS working directory D2H builds from DOCX + HTML source One project generates all targets across all products (shared content)

Our new Helpsite

Changes brewing Strong demand for community-based documentation & multimedia Continuous Delivery changing everything (again!) Writers » bloggers and editors, forum managers? Start localizing

Questions

http://www.cleverhamster.com	397
http://paper.li	14
http://cleverhamster.typepad.com	4

LavaCon 2011: Why I left my CMS! and how I did it

by Mary Connor on Nov 09, 2011

Accessibility

Categories

Tags

Upload Details

Usage Rights

3 Embeds 415

Statistics

LavaCon 2011: Why I left my CMS! and how I did it — Presentation Transcript