Clever Hamster

LavaCon 2011 presentation links

As promised at my LavaCon sessions, here are my presentation materials. Many thanks to Jack Molisani, for having me speak, and to Nicky Bleiel, for presenting with me again!

Here are the extended article versions, in Word format:

1. Download 2011-LavaCon_Developer-Docs_MConnor-Bleiel
2. Download 2011-LavaCon_Left-my-CMS_MConnor

LavaCon 2011: Double Trouble! Adding Developer Docs to Your Deliverables

 

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

Migrating from a CCMS

I've never needed a roadmap for any documentation migration project; my experience has been that content, if reasonable well-formed and well-styled, is easy enough to import into commercial tools. But I had never tried to push content back "upstream", to the friendly formats we now need for Agile collaboration: indeed, I’ve yet to meet anyone who worked to take content out of a component content management system (CCMS), having gotten it there!

And just as with moving houses, the longer you’ve lived in a CCMS, the harder it is to pack it all up, if you aren't porting to similar formats and granularity. Here are some of the tasks it required, to get us out of the CCMS:

1. Unraveled the reuse of objects so that they each occur only once in the export file set.
   This is not as horrifying and counter-productive as it sounds, for much of the reuse would simply be reimplemented in the new system; the trick is to bring over each bit of content only once. Reuse spanned the entire library, of course: books within books, topics within topics, graphics across topics. What saved us was the discipline of reserving 99% of reuse to books within books (my take on Reusable Learning Objects) and rewriting content to support that multi-context reuse.
2. Exposed all hidden notes/references/commentary/history (designed to never publish) so that it’s included in the export files and not lost.
3. Optimized object templates (such as link formatting and style assignments) for how D2H interprets files on import.
4. Wrote Word macros to achieve reproducible post-processing: resizing graphics, substituting styles, converting to Word XML (DOCX), etc.
5. Created export projects and batch files to automate the migration so we could iterate.

This last point proved to be the crucial factor, because speed of conversion R&D increased dramatically once I could kick off a new export/import/build batch to test each new theory of how to solve a problem or transform a content feature. And that is a lesson that generalizes to everything I face in documentation architecture: automation always pays.

Why Doc-To-Help and not a wiki?

Being avid followers of the sea change of social media, our first instinct was to turn to a wiki solution to support real-time, team-wide, distributed authoring. We studied the field, narrowed it to the three most promising candidates for further research, but found no solutions among them.

1. Confluence - Being the one wiki designed expressly for technical documentation, we had to consider Confluence. However, its licensing costs and its relative complexity were real barriers. It also conflicted with our technology: ours is a Windows (ASPX) product, yet Confluence hails from the Java world and does not love Internet Explorer, which is our primary browser. I’d also heard from an adopter that Confluence would choke on the size of our builds to hardcopy formats, as it was only designed to export small subsets of wiki content. 
2. Mediawiki - Being the open-source wiki powering Wikipedia, Mediawiki made it onto our short list. While many aspects of it proved friendlier and attractive, we soon ruled it out because we couldn’t publish out of the wiki format into our other needed outputs, and (more importantly) we could not secure content and access with anything like the granularity we’d need for production work. 
3. Drupal - Drupal was a finalist not only because of its immense capability (as optional modules) but also because we were long-time users: we’d used Drupal for our product’s community site for years, offering blogging and forums as well as wikis of reference information. We could secure it, extend it, completely customize its theme, and probably publish (export) outputs from it, even use complex taxonomies to create a myriad of dynamic content experiences. However, we were on version 4 and would need to migrate to 6 or 7, which would be a serious project. Worse, we knew it’d take significant expertise to program Drupal for our complex documentation requirements — expertise we lacked in-house and probably couldn’t afford to contract for.

Why Doc-To-Help?

In truth, I played with Doc-To-Help 2010 (D2H) before considering it for our solution. Some tweet having pricked my curiosity, I downloaded the eval version and tossed together a project that included the Word outputs that comprised all of our flagship product content. Instead of choking on the tonnage, D2H handily built me a NetHelp site in minutes, not hours. That got my attention: this was not the Doc-To-Help I'd used a decade ago. Its acquisition by a company that made developer tools had resulted in a serious makeover under the hood! My economy car seemed lovingly rebuilt into a racer.

These are the features that merited a proof-of-concept with Doc-To-Help:

• Single-sourcing across build targets: compiled Help, HTML, manuals, training
• Single-sourcing across source types: HTML, XHTML, Word (DOCX)
• Merging generated API and developer conceptual docs into blended deliverables
• Unifying documentation strategy across user and developer docs (one system serves all)
• Support for team authoring in Team Foundation Server (and SharePoint repositories)
• Command-line builds, for automation and continuous integration
• Familiar and available editors for source files (crucial for non-writer participation): Microsoft Office, Notepad++, etc.
• Able to handle the scale of our builds (similar build time to AuthorIT v4)
• Affordability: new licenses for the cost of our AuthorIT maintenance

In posts to come, I'll explain how we managed to migrate out of a CCMS, how our current build system is organized, and where we're going next.

People and tool reasons for migrating docs

Changing our documentation system was driven, ultimately, by personnel reasons that resulted from our switch to Agile:

House Rule: Teams must be cross-functional generalists

As part of Agile, our job titles and formal duties were dropped, so that we are all considered “Product Developers”, all collectively responsible for designing, coding, testing, and documenting. While we all bring strengths and expertise, we are no longer dedicated role specialists. Underlying this is the belief that everyone can and should write, which is key to the participatory model of social media: “Here comes everyone!”

So, the critical change is that our approach to Agile demands that all SCRUM team members be enabled to create and update documentation, to achieve Definition of Done. 

Info Dev lost half its writers

Our Agile consultant warned us to expect to lose a third to a half of our talent due to unhappiness with the new method. Ironically, all of our writers loved Agile: far from being dinosaurs who could not adapt with the times, they were lured away to other Agile shops and opportunities, such as consulting. So, losing half our resources (two out of four staff writers!), the few of us remaining were sure to become bottlenecks unless we could open the doors to wider participation.

No new writer hires likely

But Agile brought us deeper disruptions than a temporary headcount crunch. A documentation impact that we did not see coming was our Agile directive of allowing teams to decide how vacancies are to be filled, to best help them reach Definition of Done. This effectively means that a team can skip back-filling a lost writer in order to get another developer (which is more likely to increase team velocity). The new norm is to fill vacancies with junior programmers, who focus first on automated testing before being pulled into new code creation. 

The resulting negative impact on documentation volume and quality will have to be heard from customers by Product Owners, and that will take time to become clear. Meanwhile, we remaining writers straddled multiple teams and watched our silo model of documentation production (where dedicated technical writers author in a specialized CMS) careen toward extinction.

But... why not solve it within AuthorIT?

Surely the most logical first response to this personnel crisis would be to revamp our existing implementation to work with authorship across the entire production group. Here are the barriers we found, the "Tool reasons", that kept us from doing so:

• Budget for licensing - We use AuthorIT on a terminal server, with floating licenses to support all writers working concurrently. It would cost thousands to buy extra licenses/support to cover concurrent work by all the teams, and the AuthorIT enterprise webserver version (designed for exactly this use case) costs in the six figures – quite out of our reach.
• Our complex implementation - Worse, the library structure we’d developed was too complex to just open to non-writers: the nested variables, embedded topic objects, template inheritance, object-oriented structure (such as hyperlink objects), and other features of the CCMS would be nearly impossible to simplify for casual users. Reimplementing our content library for safe and easy authoring by SMEs would be a huge project in its own right - as big as conversion.
• Forced migration looming - At the same time, we faced a migration within AuthorIT, from version 4 to version 5, a project outside the scope of our active sprint work. To get to version 5, we faced reimplementing our publishing templates and macros, and we had several blocking issues on our test migration database. In other words, we had been deferring a large amount of non-sprint work, completion of which wouldn't have us any closer to an Agile solution.

That last point worried me. Before too long, we could face having our production library on an unsupported version of the CCMS, an unsupported version of Word, and an unsupported version of Windows Server. Ironically, this was the exact situation we were in back when we converted to AuthorIT! A good time to jump.

Why did we abandon AuthorIT?

In this series of blog posts, I'm sharing the huge impact that our switch to Agile development practices has had on our documentation systems. This impact includes (catching my breath) forcing us to give up using AuthorIT to produce our documentation.

If you'd told me two years ago that I'd have written that sentence, my eyes would have gone wide with horror, for our AuthorIT system is mature and powerful, efficiently automating documentation builds and publication, in all its complexity.

Many factors went into the change, so I'll group and tackle them separately:

• Process reasons
• People reasons
• Tool reasons

While process drivers from our development environment would likely not, alone, have forced our tool migration, they were substantial and complex:

New documentation outside of our CMS

A fact that would upset anyone responsible for content management, I found that our newest products and technology were being documented entirely outside of the existing AuthorIT system. All of our years of single-sourcing were being unraveled! Each month that went by, the situation worsened.

• API docs - Our new work centers on a Service-Oriented Architecture (SOA) product, which needs developer-written documentation (now done in Drupal) and an API reference (built manually using Sandcastle). Neither piece could be documented by developers in our current system.
• Configuration docs - Our new user interface is created entirely in .NET web parts,  each of which has its configuration documented in a special HTML file that resides inside of the code package. We had no way to unify this fractured source within our AuthorIT system. 

And not only is the source fractured: users are forced to look in multiple locations for information, which is unacceptable UX. Nor could we single-source this new content for reuse (such as for our training materials). The documentation situation was getting horribly complex and unfriendly.

Process goals unmet by AuthorIT

The other major area of process unhappiness was the ways in which our documentation system failed to participate in the Agile development systems that we crafted for our code:

• Continuous Integration builds - A huge change in our development practice was re-engineering to support continuous integration: it’s no longer good enough to have a feature pass tests on a local build – the code check-in now triggers a “commit” build immediately so everyone can get email notifications if the change breaks the build or any other component. This change speeds up the testing cycle immensely, helping teams finish more stories per sprint. Our challenge was how to set up docs to participate in continuous integration as well, updating all deliverables as soon as source file changes are committed.
• All source files managed in Visual Studio - Beyond continuous integration, we saw that having 100% of source material — across all deliverables — managed, branched, and built inside of Visual Studio (Team Foundation Server) streamlines all processes immensely: it grants one-and-only-one simple way to check out source, associate it with sprint backlog items, and track progress. Everyone in Production is licensed for TFS and can participate in updating documentation stored in TFS, with no change in process. 

Solving that last point brought benefits I didn't anticipate: Having documentation source on equal footing with code source does more to elevate the importance and visibility of documentation than anything else we’d tried.

Next, I'll explain the people issues that drove our migration.

How does Agile affect documentation?

Here's the rub for technical writers: Converting to Agile methods forces changes to how we create and manage documentation. In our case, documentation is supposed to be handled "like code" within the Scrum/sprint process, subject to the same requirements. So, here are the implications we deal with:

• No lagging a sprint behind, as some shops do; we must be "shippable" at Review.
  • We write up new documentation and revise the existing at the same time as it's being coded and tested.
  • Within the sprint, there's a bit of a waterfall, just as exists for testers: we can't see what's not coded yet. Ends of sprints are quite brisk for writers.
• We focus on continuous, automated builds, in support of being ready-to-ship.
  • Our build engineers worked hard to create a continuous, automated build environment to support Agile, meaning that checking in code triggers an immediate rebuild. The rebuild success or failure is broadcast throughout Production, reporting errors and test failure details, for immediate response.
  • Continuous integration builds allow testers and writers to always work with "real" builds.
  • Automated builds of documentation into Help sites and manuals mimicks this system, and it allows testers to evaluate documentation based on what will actually ship.
  • In reviews, we provide links to the actual, finished documentation changes.
• Docs are part of Definition of Done; incomplete doc tasks block the entire team.
  • Tempting as it would be to push incomplete doc tasks to the following sprint, we don't show any stories as complete if the docs aren't there.
  • To keep the tech writer (a shared resource) from blocking the team's ability to complete, other team members must be able to update doc source.
• Integration and overall review of release documentation happens during final regression sprints.
  • Editing for document flow and consistency is largely deferred until the very end, by necessity. The more cooks in the kitchen, content-wise, the more daunting this is.
  • Final regression before a general release is the only opportunity to force teams and stakeholders to review entire documents, versus the single topics affected by a given sprint.
  • All production work (new batch scripts, archiving, setting up manuals with printers, updating publication sites) also happens during this period, so the documentation team is very crunched at a time when the rest of production experiences a relatively restful break from typical sprint work.

Since a goal of Agile is to have teams work productively at an even, sustainable pace, I see real challenges in this approach to documentation: to avoid a train wreck during regression, I suspect the integration and editing functions need to be performed continuously throughout the entire release. I think this argues for placing technical editing in a supporting function outside of the teams, with an Editorial Review required within Definition of Done for any doc tasks. Do any of you manage it this way?

Agile collaboration tools

Despite our SCRUM teams being mostly collocated, only one team has no remote members. Largely because of this, we make extensive use of collaboration tools:

• Ventrilo and Skype, for VoIP voice conferencing
• Mitel (which our company licenses) for on-demand desktop sharing and video conferencing
• Yahoo IM, for instant messaging and status broadcasts (flagging our current availability)
• Typewith.me, Google Docs, and Google Wave, for group brainstorming and live editing of sprint artifacts
• Campfire, for team discussion threads (to lessen our email burden)
• Drupal, for cross-team blogs, wikis, and discussion forums
• BBFlashback, for creating informal demos, tutorials, and braindumps
• Cacoo, for collaborative creation of flowcharts and diagrams, which can be linked into wiki pages and documentation source files

Love song to Cacoo

The last tool, Cacoo, is one I'm very excited about, as it solves many longstanding problems: how to put a diagramming tool in everyone's hands, how to make diagramming easy enough that everyone will create them, and how to update diagrams collaboratively. Our sprint reviews go more smoothly when we create diagrams that capture our progress through the epic, so that our customers don't have to remember what they were shown last review and which features are yet to come.

I'm also thrilled with how it's implemented, because I can link a diagram's image (PNG format) into a web page, and it always stays current with the latest diagram updates. I can also make that image clickable, so that it opens up the diagram for editing, if the viewer has access permissions to do so. Moreover, Cacoo can take and import screenshots, so it can serve as a native format for creating and updated annotated and composite screenshots. I see a lot of potential here to expand our visual communication! 

Which flavor of “Agile” did we pick?

Saying you’re doing “Agile” clarifies little because there is so much variation in how organizations choose to implement their version of it. Here are the Agile and SCRUM fundamentals we embraced and committed to:

• We belong to collocated teams, meaning that the local telecommuters all had to return to the office (we retained our remote developers and testers, but new hires are local).
• Team rosters tend to include a product owner, a scrum master, three developers, one or two QA analysts, one business analyst, and a tech writer. (Over time, the scrum masters and tech writers became shared resources, and BAs moved into a dedicated UX team.)
• We work in bullpens, where all team members have desks facing into the center, so that we see each other instead of walls. Most bullpens lack telephones.
• We answer to product owners, rather than departmental managers, whose roles have largely been reduced to performance reviews and budgeting.
• We work in 2-week sprints, which we stagger by product lines: if those on product A start a sprint this week, then those on product B will start next week. We also start and end sprints mid-week to accommodate New Zealand developers being a day ahead of the teams in the U.S. (our Friday is their Saturday).
• Each sprint starts with Planning from the Product Backlog, from which the Product Owner presents her prioritized stories. The team adds up its capacity, estimates the points (size) of each story, nails down the Acceptance Criteria, tasks out the work items, and commits to a set of stories, whose progress we track in Team Foundation Server (Visual Studio).
• Each day of the sprint includes team standup (SCRUM) meetings plus a standup with all teams represented, to share status, raise concerns, and collaborate across teams.
• Each team’s sprint ends with a webinar Review, where the team presents its finished work to actual customers and all stakeholders, for questions and feedback. A private Retrospective always follows, for the team to give kudos and record what worked, what didn’t, and what to try differently next time, so that the process is always improving.

I'm curious to learn how this compares to the configuration and processes of other shops doing Agile. How close are we to the norm, if there is one?

Good riddance, Waterfall

My company's switch to Agile methods two years ago was not about being fashionable, any more than when we virtualized our environment and embraced telecommuting: it was pure economics. We simply could not afford another software release such as we had just completed, since it was excessively long in development, consequently expensive, and — for all of that — coolly received by our customers. The biggest risk we faced, it seemed, was not being bold enough in embracing change.

To those of you still gazing over the cliff edge of Agile, I will say that the switch went dizzyingly fast. A consultant was selected, he worked directly with management, and then all of Production shut down for a solid week of on-site Agile training by this consultant. We grouped into teams, squeezed into make-shift team rooms, selected our Scrum Masters, and were handed over to Product Owners, who started us working from a list of stories they had only just learned how to write. We were live!

So, having done Agile for a good chunk of time now and through several releases, I can happily say Good Riddance to Waterfall:

• No more ream-sized specifications, impossible to disambiguate and keep updated
• No more frustration at being signed up to complete features that look too large to be completed in the given release
• No more focus on what should be (specification), but only on what is (working software)
• No more wondering if customers want what we're creating
• No more boom and bust of release crises and post-release exhaustion
• No more wishing we knew where things stood and if we're making progress
• No more insanity of pushing a flawed feature to completion because there isn't time to do it over
• No more despair at having to ship with known bugs, because of schedule overruns
• No more feeling as maneuverable as an oil tanker, imperiled by outdated depth soundings

After 20 years of doing waterfall, it feels like a brand new game. May all your projects be agile!

Notes: Managing technical debt in Agile

This week I attended a webinar on "Managing Technical Debt with Agile" by Michael Hall, of Three Beacons. “Technical Debt” often comes from choosing a design approach for expedience that, over time, increases complexity and costs. The financial metaphor is that of credit: to get something now, pay for it later, but with interest — which can worsen to the point that all money (effort) is going into servicing that debt, which can never be paid off. Mike offered three areas of suggestions: how to prevent new debt from occurring, how to deal with new debt that happens, and how to bring down legacy debt:

• Stopping new debt
  1. Culture shift: "From this day forward, we no longer allow technical debt, unless there's a solid business justification"
  2. Strong and visible “Definition of Done”: 
     • Coding standards adherence
     • Code reviews
     • Complexity analysis
     • Written unit tests
     • 0 known bugs
     • Test cases passed, automated
  3. Test-Driven Development (TDD): write test, fail the test, then write code to pass the test. Refactor when needed. Produces higher-quality, streamlined code
  4. Collaborative Designs: More whiteboard sessions on design topics, less over-reliance on subject-matter experts
• Dealing with new debt
  1. Debt Backlog, for debt that is business-justified
     • Track DEBT by name and list work tasks associated
     • Track the "commitment to fix" schedule (which sprint to resolve by)
     • Keep the debt service level visible, and track debt dynamically
  2. “Service the Debt” Commitment
     • Always include a debt item in a sprint ASAP
     • Service the debt as you go! Keep it as close to $0 as possible
  3. "Makeup Stories": they apologize to the code base and promise to fix it!
     • Non-user story work for any time you circumvented quality
     • Add it to the product backlog, but make visibly different, for tracking/reporting
     • Prioritize into next sprint (if possible)
  4. Makeup Stories - have them "adopted" by related User Stories
     • Good way to ensure that makeup stories get worked
     • If a user story leverages the debt area, include the makeup story as part of the effort
  5. Dedicated sprint to service debt, or combine with bugfix sprints
• Dealing with legacy/inherited debt
  1. Re-Do Project (total redesign and rewrite) almost never worth it, unless for new technology
  2. “Small Chunks” Approach
     • Smaller chunks of effort done within normal dev flow
     • Can work well across an API abstraction
     • Often requires architectural assessment
     • Risk: Can require code changes to other parts of legacy base
  3. 70 / 30 Rule
     • 70% - new user stories, 30% - paying down legacy debt
     • Best with a PO who has history with the legacy system
     • Rule also works to manage new technical debt
  4. “While There” Rule: 
     • While adding a new feature, any legacy function touched must be reworked to coding standards
     • Works well for support team also (while fixing bugs)
     • Risk: may introduce bugs

“Take my advice: go well, not fast. Care about your code. Take the time to do things right. In software, slow and steady wins the race; and speed kills."
– Robert C. Martin (Uncle Bob)