• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
LavaCon 2011: Why I left my CMS! and how I did it
 

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

on

  • 2,537 views

Find out why—and how—an experienced software documentation group walked away from a fabulously successful, stable, and well-automated CMS implementation. Two forces drove us off this cliff: our ...

Find out why—and how—an experienced software documentation group walked away from a fabulously successful, stable, and well-automated CMS implementation. Two forces drove us off this cliff: our shop’s moves [1] to Agile development, and [2] to .NET-based web technology. The switch to Agile broke open our authoring silo and our department, and the switch to new web technology required documentation we couldn’t source in our CMS. Doc-To-Help made it possible to unify all of the new documentation with the legacy content in Agile-friendly ways, but first we had to extract that content. Getting into a CMS from well-styled content is easy, but find out what it takes to get your content out again for management in a new system.

Statistics

Views

Total Views
2,537
Views on SlideShare
1,605
Embed Views
932

Actions

Likes
0
Downloads
18
Comments
0

4 Embeds 932

http://www.cleverhamster.com 913
http://paper.li 14
http://cleverhamster.typepad.com 4
https://www.linkedin.com 1

Accessibility

Categories

Upload Details

Uploaded via as Microsoft PowerPoint

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment
  • Requirement SpecificationsFunctional SpecificationsDesign Specifications
  • “No one expects the Spanish Inquisition!!”
  • “If you author in the right sub-book, I can make all the outputs work.”
  • Having gotten our content out of the CMS and unraveled reuse, easy to import to whatever’s next

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

  • 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