On the Move for August

Head’s Up:  we will not be located at the Salesforce Rincon meeting room for the August 19, 2015 meeting. Please stay tuned for additional location information.
We hope you can attend, because we are planning an end of summer pizza celebration for the August meeting, in addition to another great speaker.
Advertisements

Thoughts from Our President

Although it comes up pretty often, I’ve been recently thinking more about how I would teach someone how to be a technical writer.
Spurred on by a programmer friend, I began going through online programming lessons through Codecademy. Since I don’t have any background in development, it was an uphill struggle. Luckily, my friend was there to help me. I’m happy to say that I completed a few courses and learned so much from the process.
At the start of a long car ride, my friend asked if I could return the favor and teach him about technical writing. And, I promptly drew a blank. Granted, I’ve been a technical writer for many years. And it’s been many more years since I took tech comm 101 at San Francisco State University. So, I was at a loss for how to condense my years of knowledge into chunks or even lessons.
So, I stumbled around for a while:
“Well, you have to know the basics of grammar…” 
 
“And, you need to write, but you need to learn how to write as little as possible because people don’t like reading docs…”
 
“You really need to know how to interview people…”
 
“White space…”
 
“Audience and purpose…”
 
“You’re really an advocate for the user…”
Granted, I probably could have shared more useful information if I spent some more time thinking on it, or was a skilled instructor. Looking back, it was interesting to see how difficult it was to start from zero explaining what I believe can be a difficult profession to pin down.
I’m working with an intern at work for the summer. It’s my first time working with an intern as a senior writer. And, I feel an immense sense of responsibility to share what I’ve learned with her. Luckily, as a technical writing intern, she’s learned the basics. But, remembering my earlier, sad efforts with my friend, I’m starting to think more seriously about how to share information.
I had a rocky start at my first “real” technical writing job, so I deeply understand how important it is to support those who are starting their journey in technical communication. Maybe I won’t give a perfect lesson every time, but I will try my best to be patient, encouraging, and generous with my time.

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/.

Time Marches On

Hello,

We hope you have enjoyed the new STC San Francisco Chapter web space thus far.

It seems I’ve only just agreed to take over as Editor, and yet, we find ourselves already at mid March.  Throughout this year we intend to bring you the latest topics in Technical Writing as well a current happenings for the San Francisco chapter as well as other professional writers around the Bay area.

I hope you will find interest herein where we provide our newest articles:

Our President, Leah Scampoli shares in her article about the live Webinar Trends in Mobile Software User Assistance by Joe Welinske

Technical Recruiter Shares Expertise is a STC meeting review written by Doug Bothwell

Finally, we hope to see you all at 18 March meeting at the Rincon Center. Read more about what’s happening here.

We welcome comments and suggestions for presentations and written articles. Please be in touch at info@stc-sf.org.

Enjoy!

Sherry Nugent

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.

President’s News and Notes

I recently attended the live webinar Trends in Mobile Software User Assistance by Joe Welinske. It was a very interesting presentation, and I really appreciate Joe taking the time to speak to those who registered.

I haven’t written specifically for a mobile user interface, so in addition to learning about a new documentation delivery trend, I was also interested in the topic as a consumer.

Here are points that Joe highlighted:

Small Screens Means More Integrated Help, Visual Cues and Icons

There’s a very small amount of visual real estate on the mobile screen. This means that traditional documentation formatting is often abandoned for transparent overlays or highlights. In fact, two of the latest apps I downloaded (Alien Blue for Reddit and Duolingo) didn’t even have a help system at all. After some navigating around, I didn’t find any help pages either. Instead, both apps used icons and menu headings to inform the user on where to go.

This is not uncommon for mobile interfaces. Joe indicated that fitting traditional help documents into a small screen is not a wise choice, given that people consume information in a wildly different way on their phones. However, single sourcing content but exporting for print, web, and phones makes sense without too many more steps.

First Impressions Are Important

App users need the most help on the first couple interactions with the device. Once they get the hang of the program, there won’t be much need for additional assistance, unless new or vastly updated features are introduced. Sometimes, a company will communicate these changes, with user help, via other forms of social media or some type of pop up window.

So, as the first interaction is key to a user understanding how to use the system, some companies are taking the extra step of using guided help or a getting started tutorial. This may take the form of several pages of explaining how to complete common tasks. Another common device is the use of transparent overlays or arrows directing users to where they want to go. I’ve come across this type of help in apps that have complicated or multi-step processes, such as Stellar.

 

Missed the Webinar? You’re in Luck!

If you would like to request a recording of the webinar, please fill out the contact form on Joe Welinske’s website and include the name of the webinar, Trends in Mobile Software User Assistance, and that you are part of the STC San Francisco Chapter community in the comments box.

Thanks, Leah