Date post: | 16-Apr-2017 |
Category: |
Technology |
Upload: | mary-connor |
View: | 3,660 times |
Download: | 1 times |
Why I left my CMS!…and how I did it
LavaCon ConferenceNovember 16, 2011
Mary Connor
Presenter
Mary Connor Documentation Architect,
Advanced Solutions International [email protected] 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