Clever Hamster

Capture Those Brain Dumps

Particularly in Agile shops, it's critical to grab information opportunistically: when that subject matter expert finally comes up for air long enough to discuss that new implementation you've heard was coming, drop everything and grab a basket to catch that brain dump.

By "brain dump" (dump as in download) we mean a person-to-person transfer of knowledge, often under a tight deadline (such as your expert leaving the company!) Sometimes brain dumps are live software walkthroughs, during which the SME flies through the online process, parenthetically rattling off dangers and limitations as well as future enhancements and open issues. It's what we lovingly call "drinking from the fire hose" because the information density is too high to be consumed, much less retained. In short, you're doomed: If you pay attention enough to formulate good questions, will you have taken sufficient notes? If you take good notes, will you have missed seeing the GUI process flying by on the screen?

In my experience, the best way to benefit from a brain dump is to make it a person-to-media transfer, to capture both the audio and visual information to disk so that you can review it after the fact and harvest out screenshots for reference. Use the time with the SME to pay attention actively and ask for clarification, and let the recording software do the work of capturing the details.

But how to record it? Aren't demo recording tools complex and expensive? Yes, those that are geared for formal training deliverables or commercial webinars cost real money; worse, they won't necessarily be easy to use in a brain dump situation, which won't likely take place on your computer (with your licensed recording tool) and your microphone. It can be even crazier when your SME is remote.

Here are a few tips and tools to get you started:

Don't make the SME do anything but dump.

• In my experience, it doesn't work to ask SMEs to install special software on their systems or to be responsible for managing the recordings. Find a way that is completely hands-off on their part. They're harried enough.

Think MP4.

• The MP4 video format is easily shared, uploaded, and viewed across platforms. From your Google account, you can upload this format to an unlisted YouTube video for quick distribution to team members. Done.

Start with what you already have, technology-wise.

• If your company uses Skype for chat and video calls, just use Skype for the demo. Install the Evaer recorder ($20 for unlimited videos), start a video call with the SME, have them share their screen, and record just the remote video along with the combined audio. The SME can demo this way distraction-free, since they aren't doing the recording.

Seek out cross-platform browser-based services.

• Most web conferencing services require a monthly subscription to record demos, but Zoom allows for local MP4 recordings on the free subscription. Create your account, invite your SME to your webinar, and let them share their screen and talk. If it's just the two of you, it's unlimited; for 3-50 participants, you're capped at 40 minutes.

If you've found other cheap solutions for capturing brain dumps, please share!

Bulletproof numbered styles in Word

Oh, happy dance! I've been working in Microsoft Word again (for a content migration project) and I just broke through a major pain point: I figured out how to design style-driven numbered lists that won't go wonky or ever need restarting. If you use Word for technical publications, I hope this brings you joy.

The answer is to use a multilevel list, but with a twist. Multilevel lists are known to most of us as the way to achieve numbered headings, but they also let us create hierarchical structures for lists, both bulleted and numbered:

The trick, in a nutshell, is to create a multilevel list that starts with a "zero" level above the numbered list levels, so that restart numbering always happens correctly. That zero level (here, List Paragraph, Number0) is easily put to use as the standard intro blurb to the procedure:

Here's the plumbing:

1. Create a set of styles for numbered lists based on List Paragraph.
2. Create a new multilevel list (see red circle on toolbar, below).
3. For level 1 (far left, under Click level to modify), select your zero-level style (List Paragraph) as the Link level to style.
4. For Number format, delete the autonumber (none) and put in a character (for mine, I put a pipe and changed its color, just as a visual).
5. For level 2, select your first numbered list style (Number1).
6. For Number format, tweak it as you like (I removed the period and changed the font, for example).
7. For level 3, select your second numbered list style (Number2). Tweak it as you like.
8. Rinse and repeat.

Hope this helps someone!

WritersUA Central takeaways

For my own benefit, I'm writing this quick list of goodies and action items from the notes that I jotted down from the Software User Assistance conference this week:

• Remember "pave the cowpaths" — let users develop footpaths and use those to decide where to put pavers.
• Seek out books from the Visual Quick Start and Missing Manual series.
• Study CSS3 selector syntax for controlling subordinate elements:
• td p { } = styles only paragraphs within table cells
• ol > li { } = styles only items within numbered lists
• h1 +h2 { } = styles only Heading 2s that immediately follow Heading 1
• Study CSS3 for methods to add @content, without JavaScript.
• Breaking news of MadCap buying Doc-To-Help = evidence of client-side tool shakeout.
• Visit Neospeech to hear surprisingly natural text-to-speech, available in Adobe Captivate.
• Remember elearning rule-of-thumb: accessibility compliance adds 30% to dev costs; use Captivate with all accessibility options enabled.
• Research says: Yes, use narration, but make sure that it doesn't read the slides! Distracts.
• Simplify demo recording by doing voice over existing visual or visual with existing voice. Stand and smile, for best results.
• Use variables to swap out generic verbs (select, scroll, move) with device-relevant ones (tap...).
• Use onfocus events to drive dynamic embedded help: onfocus="readxml('objectname')".
• Use 1-per-topic unique elements, such as DITA's short description, as a handy place to source and extract embedded help text.
• Consider putting embedded help strings in minimal XML files, but be sure to convert any HTML tags.
• Look up CanIUse to quickly find out what CSS3 is supported, where.
• Use Dave Gash's webfonts page for samples, links.
• Take the easy path to @font-face when possible by using Google fonts with big families.
• For non-Google web fonts, let FontSquirrel generate the needed CSS3.
• Turn to HTML5rocks for terrific tutorials.
• Follow Don Day's progress with the ExpeDITA Framework, for making DITA web-CMS-friendly.

DocOps: technical content goes Agile

I'm watching the Acrolinx webinar recording, Learn How CA Technologies Broke the Rules - their DocOps Approach to Agile, with great interest, as it explores the "DocOps" concept in a tangible case study. The presenter is Jim Turcotte, SVP, Business Unit Executive, CA Technologies.

DocOps (the merging of documentation into organizational operations) has these future-facing goals:

• agility — respond and deliver changes right away (minutes, not weeks)
• continuous updates — make fixes available immediately, trigger translation when needed
• collaborative authoring — invite the crowd: let every team member add and fix content
• customer integration — involve customer support and feedback; analyze usage and statistics
• content aggregation — pull together all content, from marketing through support

In a nutshell, the CA case study describes a platform that is a "wiki++", where powerful tools extend a friendly wiki to cover all standardization, publication, and translation needs, and beyond:

1. Collaborative authoring and aggregation: Atlassian Confluence (cloud-based, AWS)
2. Documentation production: k15t Scroll, for Acrolinx integration, product version control, and product-specific output deliverables (be they wikis, HTML, Help, or Office/print formats)
3. Automated editing: Acrolinx, for simplified technical English and standardization
4. Translation management: Lingotek, for workflow in and out of the wiki
5. UI integration: Product-specific landing pages integrate with web app, using single-sign-on
6. Communication integration: Jive communities, Google Analytics, Salesforce support, LinkedIn marketing, etc.

CA already has some numbers that show measurable results, such as 25% word count savings (via consolidation), 55% faster translation turnaround, and close to 25% efficiency gains (from trimming doc activities now obsolete). But to my mind, such results are just icing on the cake of meeting the DocOps goals, which is the key to agile content that truly pays — up, down, across, and beyond the organization.

Chromebooks at work?

I've been madly in love with my Samsung Chromebook ever since I shamelessly stole it from my early-adopter husband (and I'm not the only one who's done this, I've found). Its tiny price, feather weight, cool operation, and long battery life perfectly fit my use case for couch surfing and family travel. My high-schooler is now inseparable from her $99-refurbished Acer as well. Chromebook seems like an ideal consumer product. (Not so Netbooks, which, if you recall, dragged and groaned trying to run Windows on cheap hardware.)

But now I think I spy ChromeOS poised to storm the enterprise as a "does enough" thin client OS, despite organizations' significant fear of relying on the cloud. From what I see, demands on IT are only increasing:

• Reduce IT dependence and complexity
• Provide hyper-portable devices
• Lower hardware/software costs

More importantly, a convergence of must-have features is brewing:

• Offline mode, for getting work done without network access
• VMWare and Citrix support, for remoting to full desktop applications

With the new "desktop-as-a-service" (DaaS) subscription model, Chromebooks can serve up virtual desktops, not just web pages. That's a game changer that I can carry to a meeting, a client site, or a coffee shop!

Google docs and sheets get Workflows

Now that more development teams are using Google Docs to develop project artifacts, it's worth looking at optional add-ons that will build out the functionality that we need. 

One that fills a real need is Letter Feed Workflows for Documents and Sheets. LF Workflows quickly automates the process of sending review requests and collecting comments, edits, and approvals of a Google document or spreadsheet. 

Workflow lets you run the document through a series of reviewers (the email addresses you supply), each of whom will have a turn to edit the draft and approve the document. As soon as one review completes, the next reviewer gets an email that prompts them to open the document, review and comment, and approve.

The UI is simplicity itself: track the progress of the review just by viewing the document. And if a reviewer doesn't have the Google add-on installed, the review invitation will supply the link they need.

pptPlex adds Prezi power to PowerPoint

Office Labs (yes, that exists!) has come up with a Prezi emulator, what it calls "Plex technology". It's a plug-in to PowerPoint that lets you not only zoom in and out of slide sections but also vault between slides that are not sequential in the deck. This type of dynamic behavior makes establishing and maintaining context in the big picture much more natural. Done well, it reinforces understanding and improves retention.

It's easier to understand what this functionality adds and how to use it by watching it in action. Here is the pptPlex Overview video.

Not sure what happens when it leaves the Lab, but for now you can download pptPlex and use it for free.

Cheap and agile internal training

Internal training is a project that often falls onto the shoulders of technical writers, regardless of our instructional design background. Why? Availability and expedience, as it's typical for training resources to be jealously protected for end-user training. (It's the same reason that technical writers end up getting to create visuals and design the documentation: any graphic design resources are typically dedicated to Marketing needs.)

So it has been with me on several occasions, but this time the training project had new constraints: first, I had no authoring tool with which to make videos; second, I was not to use any Microsoft Office applications or formats, since our shop was standardizing on Google Apps for Business across the enterprise. I had to dream up a new approach, and I needed a good-enough way to incorporate video, to free me from repeating the brown-bag presentations for every new batch of analysts in our fast-growing company.

Although I cannot share links to my proprietary internal training, I can share the dirt-cheap production method that I ended up with, as well as lessons that I learned:

 

Presentation: Google Slides

• Handouts: Since I was needing to teach dense system architecture content, I found it most efficient to work backwards: to create and get technical reviews for the printable handouts that attendees would end up taking back to their desks, before I worried about breaking them down for slides.
• I used LucidChart (for previous projects, I used Cacoo) to create the handouts.
• Using it like a spreadsheet, I had one LucidChart diagram that included one tab (page) per handout.
• I used the Share | Sharing feature to include my reviewers.
• I used the Share | Publish feature to generate the on-demand PDF link for attendees.
• I then used SnagIt to take screenshots of small areas of the complex diagrams for use in the Google presentation.
• PowerPoint Features: While Google Slides (was Presentations) is a far simpler app than PowerPoint, it imports PowerPoints very well and supports more functionality via import than you can create outright. (I was clued in on this from my work with Google Docs, which supports advanced features such as fields that I imported from Word, even though they can't be directly created or edited.)
• (for all of Google Apps) When stuck on how to achieve something (such as a two-column layout), create what you want in Office and then import the slide to Google.
• Templates: I took existing corporate PPT slides and imported them into Google; the template (master pages) came over with the slide content.
• To work with imported slide templates, select View | Master.
• Animations: Although Slides supports animations, I don't see a way to apply them to master pages; therefore, it's fastest to create what you want to standardize on and use Duplicate Slide as you author.
• To manage animations, select an object on the slide, which enables Insert | Animation. Be sure to delete the animation you just inserted to get the panel open, if you didn't want it.
• If you set up progressive display, use it deliberately, to support your narration and keep viewer attention focused.
• To achieve progressive display of bullets, use On click with By paragraph enabled.
• To delay display of an object until a related one appears, use After previous.
• Drag and drop the animations to the ordering you want, and use Play to test it.

Video recording: SnagIt

Many technical writers consider Snagit to be the premier screenshot creation tool for documentation, but it's also the only video tool I needed to create my training. Through an online deal, I was able to buy my own copy for about $30. Snagit is made by TechSmith, the creator of Camtasia and host of Screencast.com, so it has basic but solid video creation abilities.

• Audio: Get a decent noise-canceling headset (such as a Plantronics), and make sure that the mic boom is low enough to escape breathing and percussive noises.
• Shortcuts: Spend ample time optimizing the key commands for recording video, because you will have to juggle both Snagit and Google Slides while you struggle to keep speaking fluidly.
• Being right-handed, it worked best for me when I reserved the right hand to drive the presentation and created video shortcuts that were convenient for my left hand.
• Select More preferences, Hotkeys, and set comfortable key combinations for Video capture start/pause/resume, Video capture stop, and OneClick Video capture.
• Options: Happily, there are really none to fuss with! Snagit only saves to MP4 (HD) video format using its own defaults, and MP4 is fine for a device-neutral, mobile publishing strategy.
• Snagit will incorporate System Audio capture if you enable it, but keep this disabled for narrated presentations.
• Pausing: With your three hotkeys, you will launch a capture, drag the recording area, press keys to start, and press keys to stop, which finalizes the video for review and saving.
• Practice pressing the keys to start, which is also your pause and resume command; whenever you want a moment to rest or rehearse a line, hit your pause keys and take your time.
• No editing: The key to using Snagit for video captures is to keep them short and your process easy, because they're essentially disposable. You will not be editing these; instead, you reshoot any problematic videos.
• File size: To keep the size of videos as small as possible, these are two strategies that work:
• Restrict the number of slides you cover per tutorial, reworking the content to support shorter videos. (This is both easier to shoot initially and less wasteful when you need to reshoot later.)
• Shrink the window size of your Google Slides presentation before you launch Snagit. Google Slides defaults to presenting in full-screen mode (or close to it), so resize the window manually.

Publishing: Google Site

Since our company uses Google Apps for Business, we host our intranet on Google Sites and make full use of Google Drive. Happily, SnagIt integrates nicely with Google Drive.

• When you press your stop hotkeys, Snagit Editor opens your video; if you watch it and find it flawed, just select File | Delete and try again.
• To keep the video, do File | Save As..., or click Send to Google Drive on your Share tab.
• Tip: To share video production between work and home, use a Google Drive folder that is fully shared between both Google accounts.
• To publish on a Google Site, simply create a new page and select Insert | Drive | Video. Google shows you only the videos on your Drive, from which you select.
• Once a video is placed on the page, use its gear icon to change the settings for how the video displays on your site.
• When you're ready to roll out the self-serve training, set up a node for the course, with each video having its own page and introduction, and enable Comments. On the last page, include the links to your printable handouts.
• Contact your Google Site administrator about what you need to do to get reports on page views/usage, if that data is needed for your project.

 Hope this helps!

Single-sourcing graphics

Screenshot rot is a persistent misery for all content production, and it will remain so until we fundamentally automate how we obtain and reference screenshots (tools such as Dr.Explain are trying). It's tempting to avoid screenshot use to escape the work of keeping them current, but that doesn't serve our visual learners. 

For screenshot maintenance across most documentation and training, the first defense is simple reuse. When using Microsoft Office instead of a content management system, I dynamically link (Insert | Picture | Insert and Link) to the same screenshot files used in the documentation, so that updating one screenshot updates it in both deliverables. Years ago, I created a production process that built Powerpoint files directly from Word-based documentation source, using some VBA magic -- the results were limited, but the set of training presentations were always as current as the latest build. 

Annotated screenshots are harder. I store annotated screenshots in my tool's native format so that it's easy to swap out the underlying bitmaps. A trick I've used in the past is to source annotated screenshots and diagrams in Visio, then use its Publish to Web feature to regenerate the set of PNG files that I can link into documentation and training. As long as the number and order of the Visio sheets in a given file do not change, the filenames that I linked to remain constant.

For release QA, I always try to automate whatever kind of "diff" batch processes I can. Sometimes comparing code files or tests can identify where UI elements have changed across versions, so at least there's a checklist I can manage and follow for the updates I need to make for the release. 

However, I'm now facing a new problem: how to single-source and maintain presentation content in the cloud. We use Google Apps for Business, not Microsoft Office, but training materials are still being created in Powerpoint (by those who have it installed) and stored privately, which defeats so much of the strategy (that all staff can search, copy, use slides).

I also need a good system for single-sourcing cloud-based diagrams that go into these presentations, but even Google doesn't make it easy to put shared Google drawings/diagrams into its own presentations. So, I'm currently sourcing in Powerpoint (which has the richest feature set) and importing into Google Presentations as the internally "published" version, but I don't see a way to automate this. Bleh.

Holler if you have any brainstorms for new ways to manage training graphics! For example, does Prezi play well with external content? do any online diagramming tools (such as LucidChart) double as credible presentation tools?

Conditional publishing in Sandcastle

The challenge: I needed to build internal and external versions of Help from the same source. Putting internal-only information into the Help project itself lets me single-source content and lets staff search across all relevant information, without jumping between sites. Putting pre-release content in the internal Help also makes it possible for reviewers and affected groups to read about and respond to enhancements that are still in development, without doing branch-specific builds and publishing.

However, conditional inclusion of files and content is not supported out of the box by Sandcastle, my authoring tool.

Why Sandcastle? For my new job, I inherited a C# API documentation project that is authored natively in Sandcastle. Although Eric Woodruff has done a magnificent job of maintaining and enhancing the project, Sandcastle remains a lower-level tool than I have ever before used as my primary authoring interface. All conceptual content in Sandcastle is written in raw MAML (.aml) and any reused content must be externalized as named items in XML (.token) files. No external HTML source files can be merged in (only included and linked), so content options are limited to these native topic and token formats.

The process I'll describe here works with the native capabilities of Sandcastle to achieve a rudimentary form of conditional builds — enough to support external builds that are a subset of the content of internal builds, all from shared files.

My discovery: This "conditional publishing" leverages three behaviors that I discovered through testing:

1. When the compiler cannot find a token being referenced, it does not fail the build; it just logs a warning.
2. When the compiler cannot find a token being referenced, it does not put garbage messaging in the help output (such as "Token not found.").
3. The Sandcastle Help File Builder tolerates having multiple projects (*.shfb, *.content) cohabiting the same space (folder), which many documentation tools do not.

So, I can selectively hide content in internal-only files that I don't let my public project see, without causing errors or ugliness in that public Help. In a nutshell, I only need to clone the critical files and have the internal project use those new files.

Which files to create

These are the critical files:

• *.shfbproj (XML project file, with all settings and lists of files that can be used in builds)
• *.content (XML map for which topic files to include in Help, with what naming and order)
• *.tokens (XML collection of named items -- tokens -- for reusable content)

If A is your public Help and B is your internal Help, these are your new files:

1. B.shfbproj ― the internal help project file, which references the new "B.*" files
2. B.content ― organizes topics that appear in internal Help only
   Note: To stack multiple content files, set the <SortOrder> properties to get B at the top.
3. B.tokens ― holds blurbs that appear in internal Help only
4. B.aml ― introduces the internal topics and lists upcoming/internal enhancements
   Tip: Set it to be the default topic for B.content.

How to add a new topic for internal Help

1. While working in the B project, create the new topic (.aml) file.
2. Position it where you want in B.content.
3. Build both internal and external Help, verifying that the topic appears only in the former.

How to add a new snippet for internal Help

1. In B.tokens (which I like to edit in Notepad++ with XML Tools), add your new token.
2. In all of the topic (*.aml) files that need it, insert the new token (<token>Foo</token>).
3. Build both internal and external Help, verifying that the snippet appears only in the former.

How to move internal content into public Help

As soon as a new enhancement is ready for release, a few quick edits can move that content into production:

1. For tokens, just cut the item from B.tokens and paste it into A.tokens.
2. For topics, just delete the topic from B.content and add it into A.content.
3. For New Features, just cut the release section from B.aml and paste it into New_Features.aml.

A final bit of bulletproofing

To avoid excessive editing of the project files (the most fragile!!), I added a final bit of automation:

1. B.bat ― the batch file that regenerates B.shfbproj and rebuilds & posts to the intranet
2. B.py ― the Python script it calls to swap the key values in the regenerated project

The trick to keeping this dead simple was to add two empty files to A.shfbproj as placeholder token and content files, so that the batch file and script can just clone A to B and substitute "B" for "empty":

• text = re.sub(r'empty.tokens', 'B.tokens', text)
• text = re.sub(r'empty.content', 'B.content', text)
• text = re.sub(r'developersupport', 'mary.connor', text) [to direct Feedback emails to me]

By regenerating B.shfbproj each time, it can never get out of sync with new content in A. Now I can sleep better. :-)