Clever Hamster

On the trail of clarity, beauty, efficiency, and universal design in technical communication.

  • Home
  • Portfolio
  • Professional Activity
  • LinkedIn
  • Twitter feed for updates
Print
Top 200 Strategists
Recommended Blog - indoition
Doc-To-Help MVP
LavaCon Speaker

Categories

  • Agile (35)
  • API (3)
  • Cohousing (3)
  • eLearning (2)
  • Homestead (4)
  • Professional (9)
  • Technical Writing (68)
  • User Experience (8)
  • Web/Tech (27)
See More

Recent Posts

  • Writing Great Error Messages
  • How asynchronous meetings speed Agile
  • Growing tech pubs on top of Confluence, like Salesforce.org
  • Why "Clever Hamster"?
  • Road to Cohousing: People over Things
  • ATX Aging & Innovation Summit
  • So, why cohousing?
  • Quick space deletes in Confluence
  • Documentation-Driven Design: Moving the Caboose
  • Keep Austin Agile 2016 Takeaways

Cool Reads

  • Winifred Gallagher: Rapt: Attention and the Focused Life

    Winifred Gallagher: Rapt: Attention and the Focused Life

  • Anne Gentle: Conversation and Community: The Social Web for Documentation
  • Chip Heath: Made to Stick: Why Some Ideas Survive and Others Die

    Chip Heath: Made to Stick: Why Some Ideas Survive and Others Die

  • Thomas Limoncelli: Time Management for System Administrators

    Thomas Limoncelli: Time Management for System Administrators

  • Nassim Nicholas Taleb: The Black Swan: The Impact of the Highly Improbable

    Nassim Nicholas Taleb: The Black Swan: The Impact of the Highly Improbable

  • Timothy Ferris: The 4-Hour work Week: Escape 9-5, Live Anywhere, and Join the New Rich

    Timothy Ferris: The 4-Hour work Week: Escape 9-5, Live Anywhere, and Join the New Rich

  • Seth Godin: Small Is the New Big: and 183 Other Riffs, Rants, and Remarkable Business Ideas

    Seth Godin: Small Is the New Big: and 183 Other Riffs, Rants, and Remarkable Business Ideas

  • Thomas L. Friedman: The World Is Flat: A Brief History of the Twenty-first Century

    Thomas L. Friedman: The World Is Flat: A Brief History of the Twenty-first Century

  • Eric Abrahamson: A Perfect Mess: The Hidden Benefits of Disorder--How Crammed Closets, Cluttered Offices, and On-the-Fly Planning Make the World a Better Place

    Eric Abrahamson: A Perfect Mess: The Hidden Benefits of Disorder--How Crammed Closets, Cluttered Offices, and On-the-Fly Planning Make the World a Better Place

Archives

  • April 2021
  • January 2021
  • November 2020
  • August 2019
  • May 2019
  • November 2018
  • July 2018
  • February 2017
  • July 2016
  • December 2015

Pages

  • Portfolio
  • Professional activity
  • Topics
Subscribe to this blog's feed

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

September 20, 2013 in Agile, API, Technical Writing | Permalink | Comments (0) | TrackBack (0)

Reblog (0) |

Adding access control to Help

Who has permission to read complete product documentation? It's by far the easier, softer way to make content fully public; however, as enterprise Help migrates to the web, this requirement to apply content security (access control) is surfacing more and more.
 
The cheap (or interim) approach to this is "security by obscurity": have your enterprise users log in to their product in order to reach the links to your Help (and add a robots file to instruct search engine crawlers not to index your site). You get no SEO benefits at all from your content, so there's the marketing price to be paid: prospects googling for your product think that no useful information exists. (Some HATs, such as HelpConsole, let you make part of the help visible to the public while securing the rest behind a login.)

Should "security by obscurity" prove inadequate, be very cautious about stacking on new authentication: If your product support is also moving to the web, it doubtless involves its own user authentication, and if your product is SaaS, that access is surely controlled. In either case, you need to implement single-sign-on with your existing system to keep your users from hating you. 
 
For out-of-the-box systems that bridge secure support with access-controlled documentation, you might look at a new breed of blended solutions:
  • Zendesk + Mindtouch
  • Salesforce + Confluence
  • Author-it Aspect
Some more thoughts on adding access control:
  • You can also take advantage of HATs that publish into CMS systems, such as Doc-To-Help publishing to SharePoint.
  • If you're working with structured content, it may work for you to deploy into a content publishing system such as Fluid Topics.
  • If you're authoring in a web CMS directly, such as in Drupal Book modules, you'll need to set up role definitions, views, and content tagging. 

Are there other authoring products that support the single-sign-on access control scenario? I'd love to hear about them!

August 20, 2013 in API, Technical Writing | Permalink | Comments (0) | TrackBack (0)

Reblog (0) |

Platform features needed for Agile documentation

Here's a growing list of what I'm noodling on of late. I've been trying to answer the question of what an ideal Agile platform should have, to support fast and lean documentation (both creation and maintenance).

Much is shaped by my observations of how merging docs into a larger self-serve/community support site raises the bar on what we can and should demand. What goodies am I missing?

Agile implementation

  • Easy to access (cloud; single-sign-on)
  • Easy to scale to more users, higher usage
  • Easy to selectively secure (serve both customer and internal needs)
  • Easy to support (hosted; no customizations to stop upgrades)
  • Easy to brand, set to custom domain, extend non-destructively (API)
  • Easy to reskin (without update breakage)

Agile authoring

  • Easy to create
  • Easy to import rich content created elsewhere
  • Easy to update
  • Easy to release (for SaaS, queue up changes for release-day publication)
  • Easy to revert, compare history
  • Easy to reuse content (variables, conditions)
  • Easy to embed media (screenshots, diagrams, slides, video)

Agile response

  • Link to/from support cases
  • Easy participation by Support
  • Notifications of changes, comments
  • Analytics reporting

Agile self-service

  • Single-sign-on with entire community/product/support site
  • Search across docs, blogs, forums
  • Easy to print
  • Easy to export
  • Easy to subscribe
  • Commenting, feedback
  • Translate on demand
  • Good findability via search engines

April 01, 2013 in Agile, API, Technical Writing | Permalink | Comments (0) | TrackBack (0)

Reblog (0) |