Why I left my CMS!…and how I did it

LavaCon 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 docs2. 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 type1. Objectives *       2. Feature at-a-glance $     3. Concepts        4. Processes, procedures5. 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 CCMS

1. Unraveled reuse so each object exports only once (single-sourcing)

2. Exposed hidden notes/history 3. 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