+ All Categories
Home > Technology > LavaCon 2011: Why I left my CMS! and how I did it

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

Date post: 16-Apr-2017
Category:
Upload: mary-connor
View: 3,660 times
Download: 1 times
Share this document with a friend
23
Why I left my CMS! …and how I did it LavaCon Conference November 16, 2011 Mary Connor
Transcript
Page 1: LavaCon 2011: Why I left my CMS! and how I did it

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

LavaCon ConferenceNovember 16, 2011

Mary Connor

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

Presenter

Mary Connor Documentation Architect,

Advanced Solutions International [email protected] www.cleverhamster.com

(will post write-up)

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

Why Agile?

Survival:

Waterfall was drowning us.

Literally.

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

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

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

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

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

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

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

So, why give up our CMS?

People reasons Process reasons Tool reasons

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

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?)

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

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

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

Tool Reasons

AuthorIT licensing

Ease of use Forced

migration looming (v4 > v5)

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

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

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

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

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

Ready for heresy?

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

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

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

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

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

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

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

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

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

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

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

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

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

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)

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

Our new Helpsite

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

Changes brewing

Strong demand for community-based documentation & multimedia

Continuous Delivery changing everything (again!)

Writers » bloggers and editors, forum managers?

Start localizing

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

Questions


Recommended