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.
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.
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.
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:
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 email@example.com.
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:
- Code Year, com, w3schools.com, MIT, udacity.com, Wikibooks.org, LandofCode.com, Stanford, Coursera, Udemy.com, Learnable.com, video2brain.com, Virtual Training Company, CodeAcademy.com, PeepCode.com, CodeSchool.com, Edureka.co, Educator.com, TotalTraining.com, TutsPlus.com, PluralSight, eclasses.org, MOOC, edX , JER Online, ed2go, CaveOfProgramming.com
- Trialware is the other answer to your prayers
- Online resources for would-be API writers:
- Sarah Maddox’ recent API doc course given at Google 1/23/2015
- Tom Johnson’s API doc how-to presentation to TC Camp 2015 on 1/24
- Peter Gruenbaum’s new API doc-related course
- Write The Docs meetups in SF (or, better yet, the Portland, OR conference in the spring)
- Opportunities and Leads:
- 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.
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.