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.

1. Why I left my CMS!
…and how I did it
LavaCon Conference
November 16, 2011
Mary Connor

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

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

4. 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

5. 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

6. 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

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

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

9. 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

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

11. 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

12. 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

13. Ready for heresy?

14. 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

15. 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

16. 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

17. 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

18. 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

19. 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 import
4. Macros to post-process
5. Automated migration so we could
iterate

20. 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)

21. Our new Helpsite

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

23. Questions