Case Study — Information Design: A Process for Web Architectural Success

Review By Riley VanDyke

The chapter’s Wednesday 20 May, 2015 meeting featured Eric Hughes’ presentation, Information Design: A Process for Web Architectural Success.

Eric described how he and his colleague Don Donoughe guided the University of Arkansas (UofA) through a re-implementation of the university system’s online Cooperative Extension Service.

The Backstory

At the time that Eric became involved with the project, the University of Arkansas’s Cooperative Extension Service website:

  • Struggled to serve a large and growing body of disparate target audiences who resided in all of the state’s 75 counties
  • Comprised an estimated 10,000 documents, the great majority of them stored as PDFs
  • Frustrated new visitors who were unable to use the site’s labyrinthine lists-of-lists navigational structure to find useful information
  • Forced existing users to create collections of bookmarks that enabled them to return to useful information they had somehow managed to find on a previous visit
  • Had as an internal team failed over a couple of years to redesign the site

The Organizational Challenge

It would have been difficult enough to solve the site’s manifold information architecture problems. Before those problems could be approached, it was first necessary to overcome predictable and unpredictable organizational obstacles.

The Cooperative Extension Service site was and is developed and managed by the UofA. This put the site in the hands of academically oriented contributors who buried the project team beneath a landslide of committees, processes, flowcharts, data, and alternative design proposals.

How Can We Help?

The UofA realized it needed help. So it invited Matriculus and design partner Donoughe Design to present a new way forward.

At the core of the presentation Eric delivered in response to that invitation were the following answers to the rhetorical question, Why Hire Us?

  • We’ll teach you to manage the site as a product.
  • We’ll tell you how we’ll know when we’re done (Or the reason you do process is to define an end point).

Observe that neither of these answers mention technologies, tools, or information architecture. Instead, those are criteria defined the project’s goals in terms of quantifying effective process and quantifying a successful result.

To the Rescue!

In response to Eric’s presentation, the University of Arkansas awarded Eric and Don the contract.

One of the first steps was to find someone on the project team who had the organizational authority the team would need to break process logjams, acquire necessary resources, and enforce order.

Having had the good fortune of a strong central contact within the UofA project team, Eric could begin focusing and distilling the previous team’s overabundant contributors and analysis data.

Whittling Down the Contributors

The re-architecting of the Cooperative Extension Service’s  website was a highly visible project and many people wanted to be seen as contributors.

Fortunately, Eric’s UofA contact had the authority to break process logjams and acquire the resources required to get things done. This individual’s authority enabled her to pare down the size of the project team to a manageable number of results-oriented contributors.

Whittling Down the Analysis Data

The preceding project team had created an overabundance of focus-group data, online surveys, log reports, executive team surveys, process diagrams, flowcharts, and more. Eric and the now-downsized project team next distilled the existing into a small subset of information, conclusions, and assumptions.

One example illustrates the scale of the problem and the steps necessary to distill the volume of data into a more useful form:

  • Before Eric became involved, the UofA project team had defined 30 target audiences for the site
  • Eric and the new UofA team distilled that list into a subset of target audiences that served as proxies for the larger, less focused set of audiences

Let the Information Architecting Begin!

Only after assembling a smaller, focused team and extracting the useful portions of the previous team’s research data did Eric feel ready to develop the site’s new information architecture.

The team used data acquired from user interviews, usability testing of design mockups, and card sorting sessions to develop a 10-page “key problems & issues document”. The key document provided a single and concise declaration of the project’s scope, objectives, and criteria for successful completion, and summarized all the previous information and analysis that had been done.

The Happy Ending

The size and complexity of the project to redesign UofA system’s Cooperative Extension Service website is impossible to convey in this brief recap of Eric’s presentation to the STC-SF chapter meeting.

What is summarized in the following paragraphs is the project team’s fundamental strategy, and the essential steps the team took to fulfill their strategic goals.

Discover and build on what has already been done: Identify the useful parts of earlier work, but don’t let the project become a prisoner of data that doesn’t help realize the project’s current goals.

Document the design and project process: The objective is not to communicate what needs to be done, it is instead to clarify what the team will need to do. Having documented the process, be ready to modify the process as required to achieve evolving needs.

Discover and address the real problems: Don’t let peripheral issues, constraints, and political quandaries diffuse the team’s efforts.

About This Review’s Author

Riley VanDyke has been a contract and consulting technical writer since 1998 and is an STC-SF chapter volunteer.

Streamlining Graphics Production in a Hardware Industry

Presented by Bonnie Kim

Visual Aids by Rebecca Firestone

Review by Mysti Berry

Technial writer Bonnie Kim shared with us the story of how ZepSolar adjusted  processes and tools to create graphics-dependent documentation in print and video more quickly.

The process originally involved creating graphics from scratch whenever any changes occurred, because the graphics had to move across a complex tool chain: from a library of specifications to SolidWorks, Adobe Acrobat, Jing, Photoshop/Illustrator, and InDesign/FrameMaker. Changes due to inconsistent visuals, product design changes, or content errors meant starting over.

Bonnie’s team stopped editing files in PDF and Jing, and started doing all editing of files in SolidWorks Composer, reducing many of the round-trips required when changes occurred. The team used more sophisticated SolidWorks tools, like transforms and annotations (labels, arrows, and “diggers”), to make production of the graphics faster.

Animation for video is also easier to create because SolidWorks has sophisticated tools that make many things easier, like specifying camera view (also available for print graphics), or intelligent views that save the placement and orientation of components or sets of components. They can apply the same transformation across many static views, and save the transformation for later use.

With the tools adjustment, the workflow is a simpler process, from pulling specifications from a library through SolidWorks assembly, composition, layout, and edits. Of course, every tool has its strengths and weaknesses. Bonnie shared with us that imports can be tricky in SolidWorks; it has a high price tag, and there are a few bugs in the program. Nonetheless, the professional look and feel, new vector-graphic capabilities, and small, efficient files all make SolidWorks the right solution for her team.

Bonnie’s changes can be applied to software documentation production as well. Simplifying your tool chain and reducing the number of repeat round trips required for any task applies to software documentation as easily as hardware.

Bonnie recommends that every team learn the product they are documenting as thoroughly as possible, and then get training for your tool as it likely can do more than you realize, and then, let members of your team specialize. Of course, everyone should have a certain level of versatility, but when deadlines loom, specializing in certain skills can speed up production.

You can find out more about ZepSolar at http://www.zepsolar.com/, and SolidWorks at https://www.solidworks.com/.

Technical Recruiter Shares Expertise

Review By Doug Bothwell

Andrew Davis has been a Technical Communications recruiter in the Bay Area for more than 20 years. As a former professional technical writer and Technical Publications manager, he knows the value that tech writers can add and what companies are looking for.

Thanks to Mysti Berry and Salesforce, the San Francisco STC chapter was able to book a large training room to handle the high turnout on February 18. The presentation was split into a prepared talk and a Q-and-A session.

Part 1: Make Yourself Marketable

Highlights from Andrew Davis’ presentation:

  • Mobile, Big Data/Analytics, SaaS/virtualization/cloud, Security, Open Source arenas are hot
  • Open-source companies often sell documentation–that’s how many of them make money
  • Technical Knowledge–Train yourself and become marketable. Some helpful resources include:
      • MOOCs (massively open online courses) are the answer to your prayers, and ignoring them is self-sabotage. Explore one or more of the following—register, learn, and write something using your new knowledge:
      • Trialware is the other answer to your prayers
      • Online resources for would-be API writers:
      • Write The Docs meetups in SF (or, better yet, the Portland, OR conference in the spring)
  • Opportunities and Leads:
      • Networking (still the best)
      • Recruiters
      • Job boards—Beyond the obvious choices, here are good ones:
        • LinkSV for discovering off-the-radar prospects
        • LinkUp for current, under-publicized listings
  • Employers are looking for people with
      • Excellent research, analysis, organization, writing, editing, and production skills
      • Autonomous technical learning and tool/system troubleshooting ability (aka fearlessness)
      • Deep interests in one or more technical sectors and current technical tools/development languages
      • Software experience, ideally involving some code-reading, code-commenting, and even amateur programming

Contact Andrew directly for more from his Help Me Help Your Resume document at his website www.synergistech.com.

 Part 2: Q & A with Andrew Davis

“What are the skills that companies want in writers but have the most difficulty finding?”

Software development skills–folks who can develop in their own environment without any help. Many development teams are looking for someone like them (i.e., fellow developers) who can and want to write, but these candidates are difficult to find. They want people who can write documentation that gets newbie developers up-and-running with key features as quickly as possible (ie, a short TTFHW–“time to first ‘Hello World’).

“What kind of volunteering work looks good on a resume?”

Work for professional organizations related to the Tech Comm field–it shows you believe in your profession. But don’t just limit yourself to STC–there are lots of other organizations out there. For example, Write the Docs has regular meetups that are well-attended by writers in the open-source space. These folks are more focused on deep dives into technology and supplying relevant content to developers; they’re less focused on authoring tools, DITA, and other topics that are primarily of interest to tech writers.

“How do you answer the interview question: ‘Where do you see yourself in 5 years’?”

You should answer this question seriously, even if it might be kind of old-school. It’s best to say something like “I want [more of what I want],” without getting too specific. Consider this an opportunity to tell them something about you that they don’t already know, that’s not on your resume, but emphasize how your goals can benefit theirs.

“Many interviewers don’t like interviewing and are not very good at it. Their questions are often vague and not targeted. How can I help them get the information they need?”

You should be able to say, in three minutes or so: “Here is what I’m guessing you need, here’s how I can meet those needs, and here’s the proof that I’ve done so.” An audience member suggested that you ask: “What are the biggest problems you have regarding documentation?” This offers you a chance to show how you can solve their problems; Andrew agreed, but said you need to be careful not to sound too strident nor too modest. There are times in an interview when the person who talks the least wins.

“How do you handle the issue of no-reference policies that many companies have today?”

One way to handle this is to ask someone for a LinkedIn endorsement that stays unpublished until after the person leaves the company. Also, some people might be willing to provide “off-the-record” endorsements. Note: If you contact someone asking for a reference/endorsement, it’s best to do it via cell and to do it after hours.

Someone pointed out that many companies don’t give out bad references these days for legal/CYA reasons. Andrew said that’s true, but some people still give bad references off the record.

“Are companies still unreceptive to candidates from outside the industry?”

Yes, so highlight experience you have that’s relevant to the position you’re looking for. It shows you’re in touch with their requirements.

“How do you deal with people who have no idea what tech writers do?”

Talk to them in terms of the problems you can solve and the money you can save and/or make them. You need to be able to “show your stuff” and get specific about the ways you can add value. Tech writers can do a lot beyond simple wordsmithing! And everyone cares about looking good on paper.

“Where do you see the field in five years?”

Most API documentation will probably be automated in five years, though tutorials and getting-started documentation probably won’t. UI/UX documentation probably won’t be automated. A very useful skill is being able to assemble teams and get things done…but beware Tech Pubs Manager or Doc Manager roles if they don’t involve creating product-related content.

Check out Andrew Davis’ website, www.synergistech.com—it’s a huge treasure trove of valuable information for folks looking for work, and those looking for workers.

Doug Bothwell has been a technical writer since 1999 and is currently a Lead Technical Writer with Riverbed Technology in San Francisco.

October 2014 Meeting Discussion: Publishing Strategies for API Documentation

Presented by Tom Johnson, and reviewed by Mysti Berry

Tom Johnson, author of the blog I’d Rather Be Writing (idratherbewriting.com) shared current practices and trends in API publishing. Access the slides and recorded meeting from his website(http://idratherbewriting.com/2014/10/16/api-doc-presentation-slides-and-recording/).

Hint: Be sure to look for his list of API sites to study, and the ten trends and anti-trends in API documentation.

Important features for any API documentation include:

  • A getting started section, including how to import a native API or simple queries for a web-based API. For web-based API, you may need to just pick a language, like cURL and JSON. Most companies don’t have enough in-house resources to produce every example in three or four languages, so find out what most of your customers use.
  • Many examples, especially robust examples, using syntax highlighting and adding narrative explanation to clarify the example. Some documentation displays a “copy this example” tool as well.

Tom explained the two different types of API:

  • Native: you download an API and add it to your development project.
  • Web-based: SOAP, REST, or similar interfaces are available to anyone with the correct credentials. You can usually create projects in whichever language you choose, as long as you can send JSON or XML to the API and receive the results.

Techniques that work for native API may not work for REST or SOAP. For example, auto-generated documentation is difficult for REST, which relies on URLs and standard HTTP methods.

Key trends include:

  • API documentation that looks beautiful.
  • Navigation that favors scrolling over link clicking.
  • A growing a desire to combine automated content with content that writers create.

There are features that no one wants, mostly as a result of most developer’s preference for scrolling rather than link clicking:

  • Collapsible sections and short topics
  • PDF-only
  • Tri-pane HTML

How can a writer create beautiful, scrolling content for their API developers? Tom presented over a dozen tools by category. Hosted solutions, wiki-type solutions, DITA, site generators and content auto-generators like Doxygen or Javadoc. Each has its benefits and drawbacks. Check out his slides for a fantastic list to help you start exploring the options.

Tom shared his experience using WordPress, and several other wiki-based approaches. Some people think of WordPress as a platform for non-technical blogs, but Tom’s work showed that it can integrate with DITA.

During the Q&A it became clear that tools and processes differ widely depending on whether you have a small set of interfaces or a large set, and whether you are the “lone writer” for your API efforts or have a team of other writers and developers to support you. Finally, it’s clear that a lot of people are trying to invent the perfect solution. Tom made it clear that we have a few years of experimentation and new solutions to work through before any one solution becomes the default.

Bio: Mysti Berry writes enterprise software documentation, including SOAP and REST API documentation. She currently lives in San Francisco, and works for Salesforce on the developer documentation team.

September 2014 Meeting Discussion: EPUB Help: A Viable Help Delivery Option?

Presented by Scott Prentice, and reviewed by Riley VanDyke

The first thing to notice is the question mark in the presentation’s title. The most recent version of the EPUB standard, EPUB 3, includes many but not all of the capabilities that could enable it to supplant older single-file help systems such as CHM or HLP. At the same time, the tools and readers required to author and view EPUB Help lack key capabilities.

There’s good news and not so good news

Today there is both good news and not so good news about using EPUB to deliver help content.

The good news:

  • EPUB 3 can deliver text, images, and multi-media content in a single ZIP-like archive file
  • EPUB 3 readers exist for nearly every device and platform
  • The EPUB specification is actively developed by the International Digital Publishing Forum (IDPF)

The not so good news (as of today):

  • Reader support for EPUB 3 is inconsistent or nonexistent
  • Configuring EPUB 3 to behave like an online help system is technically demanding and labor intensive
  • Tools support remains limited and can be pricey

Overview OF EPUB 3 format and capabilities

As a result of the IDPF’s active stewardship of the EPUB specification, many of the capabilities required to use EPUB to deliver help content already exist.

What works now:

  • EPUB 3 can provide a “Web site in a box” that can contain HTML5, CSS3, SVG, scripting, MathML, and multi-media files
  • EPUB readers support TOCs, indexes, search, bookmarking, and Previous/Next browsing
  • EPUB 3 supports responsive layout via media queries
  • Wide tables and images can be made to work

What will work soon (we hope):

  • Context sensitivity
  • Cross-book linking

EPUB Help development capabilities and challenges

EPUB Help developers are challenged by limited tool choices, inconsistent or nonexistent support for EPUB 3 features by most EPUB readers, and to a lesser extent omissions in the current EPUB specification.

What can be done today:

  • Use JavaScript to provide topic-based presentation via vertical scrolling
  • Use many third-party JavaScript libraries
  • Implement responsive layout via media queries

What’s harder (or today impossible) to do:

  • Most readers do not yet support the full EPUB 3 specification
  • Tools don’t support EPUB 3’s “interesting” features–you’ll need to hand-code
  • Context sensitivity via command line parameters is not yet supported
  • Kindle format presents its own separate set of challenges and limitations

What’s next?

As stated above, the IDPF actively manages the EPUB specification. Surprisingly, however, the use of EPUB as a medium for the delivery of technical communications is not at the forefront of the IDPF’s concerns.

To help make the EPUB specification a better platform for the delivery of help content, technical communicators should:

  • Encourage reader providers to support full text search and command-line driven context sensitivity
  • Encourage tools vendors to actively support EPUB 3 features (and beyond)
  • Experiment with the medium, help identify needs and future direction

Resources

Use the following resources to learn more about EPUB, EPUB readers, and EPUB development tools.

Specifications and EPUB3 compatibility:

EPUB 3 readers:

EPUB 3 tools:

Riley VanDyke has been a contract and consulting technical writer since 1998.
Riley actively volunteers with STC’s San Francisco chapter.


 

August 2014 Meeting Discussion: Sustainability Thinking for Technical Communicators

Presented by by Linda Urban, and reviewed by Sherry Nugent

Sustainability in the Bay Area has been done before and will, by its very definition, live on. However, this subject of sustainability was tackled head on as Linda Urban, award-winning technical communicator and instructor, presented Sustainability Thinking.

As a native San Franciscan, the ideas of focusing long term and considering a habitable future are not new to me. However, how do I, a technical writer of 13 years, view sustainability within my profession? Our room of technical writers pondered this question as Urban lead with talking points.

Where does the work of professional technical writers fit? What is corporate social responsibility? More generally, what is our part in today’s impact on the future? Can each of us take time in our day-to-day activities, whether it is work or play, and assess our actions toward the next generation? Linda explained how this thought process, which is often delayed or indirectly ignored, addresses the triple Ps: People, Profit, and Planet. This can be as simple as technical writers as people, profit from corporations, and the planet as our next generation.

Earlier in the day, caught up in my own world, I began to define sustainability as a technical writer quite literally. How do I ensure my employment through the changes of economy and technology? Already my status as an employee has been abbreviated to contractor. My role as contractor is more sustainable as I’m likely to be hired for several short term projects fitting a budget and much less likely to find a fulltime permanent employee position. I’ve risen to the challenge of becoming more technical to produce developer documentation whereas traditional written user guides are shorter and taking on new forms. In fact, several known colleagues are seeking higher education in instructional design as content is being reformatted for speedier communication (video et. al.) onto smaller landscapes (mobile apps et al.).

In the discussion, Urban stressed that this topic was a conversation needed from and among us all in the ‘real’ world and likewise within our culture of communicators. As she pulled us into conversation she explained her lecture was not finite and that she, in fact, was continuing and hoping to develop a complete lecture on sustainability. So as she plied us with questions and I listened to colleagues define their own meanings of sustainability, I quickly became amused as the lecturer herself aimed even to find sustainability for her future presentation. Developing a ‘complete’ lecture on sustainability seems impossible, in as much as sustainability means to meet the needs of the present without compromising the ability of future generations to meet their needs.* Wherein, the “the needs of the present” is forever changing.

So for now we focus on the present and how it might affect/improve/sustain the future. What ‘stuff’ is in our life and lives, and what replacements or cut backs can we endure and afford to ensure a better future. Sure, I can take the time to separate my daily rubbish into three recycling bins and a landfill bucket. However, coming up with the necessary $38,000 or more to adapt my 15-year old home for solar panels in an effort to conserve energy and yield me returns, that will be spread over 30 years, is much harder. It is my personal belief that one reason corporations and, even, conscious individuals, are short sighted in sustainability efforts is the capital and due diligence it requires to effectuate good for the long term. Urban thoughtfully responded to my criticism by stressing there are a multitude of means in the process and not all are costly implementations. Her response did not address the high expense (which does exist), but rather remained focused on availability of lesser costs measures. Regardless, her influence and insistence on a beginning focused on knowledge and the sharing of knowledge for sustainability will spread farther than if she did a 72-line-item cost analysis of paper harvesting in the rain forests or a comparison of consumption and connected-sub-systems weighted down by numbers.

As Urban led this sustainability discussion it appeared to touch each of us and ignite a thought process for life in the future. Specifically, how our life today affects life in the future. In her presentation, she introduces ‘backcasting’ as found on the website, www.naturalstep.org. Ironically, this process, which is visualizing the future and working backward from that vision, is identical to a corporate culture ‘success point’ recently expected of me from a global software manufacturer client. As managers, we are instructed to lead our teams to success through the thought process that begins with “the winning picture I see is. . .”

There is no better example of conscious-sustainability thinking than from the makers of Levi’s jeans. After our session with Urban, one can easily imagine the marketing and brand managers discussing and creating Levi’s winning picture in the drawing room. In a land of drought, water consumption on everyone’s mind, Levi’s jeans rolls out the campaign Jeans That Save Water and focuses on the minimal water used in the finished process of making the famous pants. This is in addition to the less structured message of ‘don’t wash your jeans’ that has perplexed some cleanly consumers.

In fact, if you own Levi’s jeans, a little bit of sustainability may just be in your pocket already.

*Brundtland Report (“Our Common Future, World Commission on Environment and Development,” 1987)

Sherry is a native San Franciscan who has returned to the Bay Area after living 10 years in Europe. As a professional technical writer, Sherry enjoys studying and employing the diverse methods that continue to broaden, and yet, focus documentation for today and the future. Currently, she manages API documentation for a leading San Francisco bank.

July 2014 Meeting Discussion: Video Tutorials

Presented by Dean Atchison and Michelle Sharon, and reviewed by Hallie Sinor

When stumped, customers prefer viewing targeted “how-to” videos over an A to Z reference source. So much so that your customer support satisfaction ratings can soar once you begin providing these gold nuggets. So how does a doc team or tech writer begin? To guide us on this journey, trail blazers of salesforce.com’s video effort shared best practices from their own experiences creating user assistance videos. Dean was the team’s first video specialist, and Michelle led the doc team’s video effort for the past two years. Spencer, the newest team member, specializes in motion graphics.

Video creation is time intensive–prioritize. Every narrated 2 – 4 minute video takes approximately 40 development hours to create, including review signoffs, etc. Once word spreads that your team is creating “how-to” videos, expect to be swamped with demand. How to best manage the onslaught of demand?

  • Select requests which will have the most impact.
  • Choose pain points with simple, direct answers over complex topics involving decision trees. Trainers and the Customer Service Team can help you identify your top pain points.
  • Determine learning objectives first to keep videos succinct and targeted. What problem are you solving, and what would you like users to walk away being able to do?
  • Create and share style guides, script templates, and audio tips to leverage subject matter experts.

Grow at least one member of the documentation team to be the video expert who will support other writers on the team. Why? Because acquiring expertise in scripting, audio recording/editing, screen capture and syncing involves a learning curve. It is difficult to simultaneously capture screen capture and audio narration. It’s easier to focus on developing quality ingredients which you sync together into a final video at a later time.

Our speakers recommend Camtasia screen recording software with its accompanying tutorials and sample script. It’s easy to use, and has smooth zooming and panning. Capture large, HD 1080p (1920 x 1080), and save to the MP4 file format. Camtasia’s extend frame feature speeds syncing a longer audio with shorter screen capture. A resource slide may be placed at the end of the screen capture to direct viewers to associated help resources.

Write an outline and script prior to recording audio. Once you select and determine objectives, time spent scripting will save you hours down the road editing. To expedite scriptwriting, you could do an informal Q and A with the subject matter expert (SME). Most importantly, require stakeholder review of the script (including SMEs, support, PM, Marketing, etc.) for accuracy prior to recording. It is best to record on the same day, taking multiple takes if an item has the potential to change. You may wish to update the script while recording if you’re making changes on the spot.

Good audio can make or break the video. Record in a small space without concrete, windows to the street, or brick. You can construct your own sound booth or use Porto-Booth Pro. Two microphones the team suggests are Blue Microphones Yeti USB Microphone ($100), and Creative Labs HS-1000 Fatal 1 ty USB Headset ($40).

Require a draft of the video for review, and let users review the usability of the video prior to posting. You can host your video on YouTube or Vimeo-Pro, or bundle with your product. Each has its pros and cons. Each time you update a video on YouTube it will get a new url. A workaround would be to upload the new video to a YouTube playlist url.

Video will give your documentation team high visibility. If you keep your how-to videos well curated, maintained, and current, they will develop a reputation with users as the place to go. Partner with your Marketing and Support departments to promote your videos. Link to them from customer communities, online blogs, and social media sites to spread the word to your customer.

For more detail, refer to the webinar link from July’s meeting.

Hallie is a learning consultant who helps organizations learn faster than their competition does. How? She collaborates with your subject matter experts, creating performance-based learning experiences yielding the competitive edge.
Hallie actively volunteers with STC’s San Francisco chapter.