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.clever...
Why Agile? Survival: Waterfall was drowning us. Literally.
Which flavor of “Agile”?               bullpens, no phones               Team = PO, SM, 3                dev, 2 QA, 1 BA...
How do we collaborate?   Ventrilo and Skype   Mitel, video conferencing   Yahoo IM   Typewith.me and Google Wave   Ca...
How does Agile affect docs? Full pigs (committed to teams) No lagging! Docs are part of Definition of Done;  incomplete...
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 wri...
Process Reasons New authoring outside  of CMS!  1. Web part docs  2. Web services (API) docs Goals unmet by AuthorIT   ...
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...
Why Doc-To-Help? Single-sourcing across targets  and sources: HTML, XHTML, DOCX One strategy for user and API docs Team...
Ready for heresy?
Our earlier crisis, B.C. Pre-CMS, Word-based source Doc and Training diverging horribly President’s command: Thou shalt...
Turned to Instructional Design Tried topic-based writing   poor results   lacking clear context and audience Studying ...
Our “learning object” content unit Learning unit, for specific user type  1.    Objectives *  2.    Feature at-a-glance $...
Just enough granularity: Score! In CMS, sub-book = RLO Arrange into publishing  books, for reuse needs Sub-book embodie...
You heard me: Don„t reuse topics! Migrating to CMS, I outlawed “topic-  based authoring” in favor of “sub-books”  (RLOs)...
Migrating from a CCMS1. Unraveled reuse so each object   exports only once (single-sourcing)2. Exposed hidden notes/histor...
Our Doc-To-Help Configuration D2H installed on test + build machines Source editable on any TFS machine,  by every Agile...
Our new Helpsite
Changes brewing Strong demand for community-based  documentation & multimedia Continuous Delivery changing everything  (...
Questions
Upcoming SlideShare
Loading in...5
×

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

2,455

Published on

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.

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
2,455
On Slideshare
0
From Embeds
0
Number of Embeds
3
Actions
Shares
0
Downloads
19
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide
  • 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

    1. 1. Why I left my CMS! …and how I did itLavaCon ConferenceNovember 16, 2011 Mary Connor
    2. 2. Presenter Mary Connor  Documentation Architect, Advanced Solutions International  mconnor@advsol.com  www.cleverhamster.com (will post write-up)
    3. 3. Why Agile? Survival: Waterfall was drowning us. Literally.
    4. 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. 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. 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. 7. So, why give up our CMS? People reasons Process reasons Tool reasons
    8. 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. 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. 10. Tool Reasons AuthorIT licensing Ease of use Forced migration looming (v4 > v5)
    11. 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. 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. 13. Ready for heresy?
    14. 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. 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. 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. 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. 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. 19. 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
    20. 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. 21. Our new Helpsite
    22. 22. Changes brewing Strong demand for community-based documentation & multimedia Continuous Delivery changing everything (again!) Writers » bloggers and editors, forum managers? Start localizing
    23. 23. Questions
    1. Gostou de algum slide específico?

      Recortar slides é uma maneira fácil de colecionar informações para acessar mais tarde.

    ×