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.

June 2014 Meeting Discussion: What’s In It For Me?

Presented by Liz Fraley, and reviewed by Eri Funada

Getting What You Want In Life

The presentation was meant for any professional situation, but the method itself is applicable to everyone’s personal and professional life. We live in a society, and people’s lives, especially when they live in a city, people’s lives consistently intersect with other people’s lives. If you have an idea that you want to implement in your real life that can’t be accomplishing by yourself, Fraley’s method is a great way to convince and get them involved in your idea. After all, not everything goes your way, but if you think your idea is a win-win solution, it’s better for everyone to benefit.

WIIFM

The keyword Fraley stated was What’s In It For Me (WIIFM). She gave an example of us coming to the meeting, and the reason we came was that there was something beneficial for all of us. WIIFM describes the idea that everyone is willing to do things that are beneficial for them. The key point is that when convincing someone to do things for you, you should talk in THEIR language, not your language. Great ways to do this are to:

  • Avoid focusing too much on the feature
    No matter how great the features are, your listener probably won’t care about what it does.
  • Avoid using highly technical vocabulary
    WIIFM for them is not the same as what it is for you.
  • Changing your perspective
    Your great idea may be great for you. But maybe what your listener is looking for is something that’s NOT what you care about. How is it going to affect the team’s finances? How about the team’s weekly schedule? Be specific and try to look in every direction.
  • Get someone to help think this out
    Some people are better at some things than you are. In Fraley’s case, her husband helps her out when she needs to persuade someone. It may be your coworker, your family, or your friends. Try talking with someone next time you’re working on a situation.
  • Try some techniques used by innovators
    There are strange online advertisements about making your life better, but not all things are suspicious and questionable material. Some people are experts and they can identify opportunities, problems, relationships, motivations, connections, and associations.

A Bad Customer Can Hurt You, but a Bad Team Can Hurt You Faster

Fraley says that authority does not help you to get people on your side, even if it’s the CEO of the company. An unwilling team in worst case can even lead to sabotage, which will reduce the efficiency of the workforce. This is not what you want. Investing in time beforehand and telling your workers how they will benefit are things everyone in your team will like. Take the time to honestly speak out about how they will benefit, and everyone in your workplace will be happy.

Eri Funada is a Technical Communication student at San Francisco State University.

 

April 2014 Meeting Discussion: Reuse Strategies to Support the API-ification of Your Content

Presented by Mysti Berry, and reviewed by Frank Welsch

What emerging benefits are there in smartly structured technical documentation authored in a robust tool like DITA? Mysti Berry, veteran STC presenter and principal technical writer at Salesforce, brought attention to one such area at the April chapter meeting.

Berry first explained that in her presentation API-enabled content means a library of granular information chunks with consistent internal structure such that a machine could automatically capture relevant content for a new delivery channel. A successful reuse strategy generally entails smartly crafted standalone topics, which are complementary to one another and non-redundant. A gifted information architect who knows the authoring tool helps by sharing with all writers a well-defined subject schema (often referred to as the highfalutin-sounding taxonomy). If the source files adhere to a sharp taxonomy, so much easier it is for the documentation team to apply the metadata attributes and content references on the library for “API-ification.” For example, the API layer can grab a collection of topics that is appropriate for a desktop screen, a separate (perhaps smaller) collection for a tablet, and maybe just a single topic for a smart phone–all without human intervention.

Social Media and Content Strategy

Nowadays the most talked-about delivery channel is mobile technology. But what is driving the attitude of “Just tell me what I need to know” is not mobile devices per se. Instead, the demand is from growing numbers of users who do not want to navigate through a linear narrative. The growth of customizable devices and social media has created the expectation of a personalized experience.

Berry spoke of noted content strategist Karen McGrane as a visionary in the field of automated reuse. Search the web with keywords “NPR” and “McGrane,” and you will find numerous web sites that discuss how NPR is a pioneer in this area. However, Berry noted that most organizations have not yet reached the day when content reuse is fully automated. Rather, more realistically, she presented ideas on how to prime documentation for the time in the future when industry standardization will enable an API layer to reach all output devices.

Expend Resources to Maximize the Business Return-on-Investment

Automated smart reuse requires less actual writing. Technical communicators are freed to concentrate on crafting polished documentation and are less worried about the production and overhead of disparate information deliverables. Berry noted that this paradigm shift fosters the innate curator role of the technical writer.

By bringing your content outside “an HTML silo,” technical communicators can provide product information to prospective customers and reduce the resources required for sales support information deliverables. Berry posited that customers are not accustomed to automated content integration, which could give the company an opportunity to sell what the customer perceives as a customized information experience.

The value-add aspect of technical communicators could be summed up in the tagline that Berry has under her email signature: “Principal Technical Writer . . . we do so much more than write.”

How Do We Do It?

Berry shared a lot of practical advice about her experience working at Salesforce. In some cases, she had empirical findings about user behavior to back up her claims. For example, she and her colleagues have observed that users who do not find the information they need in a topic generally do not click on any links to related documentation that appears in the topic. Instead, if a topic does not have the answer, users are more likely to abandon the documentation altogether or start a search on key terms. While the tips she shared involved DITA as the authoring tool, many principles could probably be transferred to companies that use other authoring platforms.

Avoid excessive metadata tagging on the file level. Imagine 30 values times 10 different qualities, along with the overhead of filtering these metadata. This is a lot of work. It is also messy work to go into each topic to change metadata or to add and remove values as your library evolves. Consider instead grouping metadata by tagging chunks of topicref links in .DITAMAP files. (For DITA novices, picture this as roughly assigning tags and values to a virtual table of contents so that relevant content appears in the corresponding contexts.)

Minimize inline xref linking. A topic that contains a list of xref elements is probably not optimal usage of DITA. Manual work is required when the target topics disappear or change. The maintenance files for reusable text strings and content filtering, such as the content references file and .DITAVAL files, should be designed to autogenerate topics or a list within a topic that pertains to the user context. With manual links, the documentation team becomes less vigilant about “conditionalizing” the information. For example, an embedded xref link to a topic about a specific product feature that is not available in all versions of the product may readily slip past the writer’s attention.

Point the user back to the UI if possible. Be sure not to repeat what the user interface already tells or shows the customer (embedded assistance). (And let’s hope that the UI developers have been receptive to input about embedded assistance from technical writers!) If a single topic cannot contain everything that you need to tell the user, it is most effective to steer the customer back to the UI if the path of action or associated knowledge base can be gleaned there.

Use a content reference for reused text strings that do not warrant topic files. Short blurbs such as “Select x > y > z to open the abc window” can be set up as reusable text that can be invoked by a conref link.

Find out how customers really use the content and what they think of it. It’s easy to get hung up with the opinions of your colleagues. Technical communicators need to engage with the customers to get a reality check. Berry shared an interesting anecdote. At Salesforce, the technical writing team has on occasion deliberately published a poorly written topic to elicit comments and suggestions from the customers!

March 2014 Meeting Discussion: Ageism and Today’s Technical Communicator

Presented by Andrew Davis, and reviewed by Andrew Garris

This month’s Society of Technical Communications (STC)–San Francisco Chapter meeting provided good information as well as a pleasant and cozy atmosphere. Light refreshments were served, and Andrew Davis executed a great presentation detailing aspects of ageism, and how ageism impacts content development projects.

Andrew Davis has been recruiting technical writers (content developers) for more than twenty years. He started in 1986 with the help of friend and mentor Jim Dexter.

Andrew began his presentation by explaining the definition of ageism, which is the predisposed opinion of an individual based solely on his or her age (age discrimination). He discussed potential assumptions that employers are likely have against older potential employee candidates. He also offered some advice to older candidates to counter the age discrimination. In addition to ageism, another existing problem in the tech industry is that the hiring manager’s expectations will greatly differ from pragmatic results that recruited employees can produce. The impact of these two issues hurts an older candidate based on the hiring manager’s perception or misinterpretation of the position of a content developer.

Hiring managers or hiring teams will often seek an employee that is familiar with the company’s content as well as having the ability to write well. We all know that this expectation is not realistic, so recruiters are left with the task of “bridging” writing personalities (those that are not familiar with technical content), with engineering personalities (those that develop hardware, software, etc.).

“Engineers like to be engineers. . .a bridge is possible. . . writers want to be writers, and sometimes they (writers) will oppose technology in pursuit of that. . .” -Andrew Davis

“Companies desire someone that understands the engineering side. . . you need to know about their technology to get your foot in the door” -Andrew Davis

There are some key things to consider when seeking job opportunities as a technical writer, content developer or technical communicator of some sort. Location, age, and experience are the three major factors to look at when determining your job ventures. Fortunately for us in Northern California, technical writers make a higher than average salary compared to the rest of the country. There is a negative side to this as well; overhead and costs of a veteran technical writer are more expensive than a younger candidate. Companies will offset this by hiring younger employees that earn less money than a seasoned technical writer. Some companies actually recruit employee candidates directly on college campuses, often with an engineering background. The company can then utilize the student as a writer or engineer.

Until recently, younger candidates were not as big of a threat to veteran technical writers. The dot com failure flooded the market with seasoned local talent, causing a lot of job opportunities for experienced technical writers. Good technical writers were hard to find for a while, causing the existing pool of tech writers to have better compensation for their work.

About ten years later, the younger generation closed the gap between them and the experienced, veteran technical writers already in the field. Companies also looked to expand in areas such as marketing communications, content strategy, and other avenues as an alternative to technical writing in an effort to cut costs. The combination of the two trends made for a unique new marketplace for job opportunities in the field.

In the restructured and recovering tech industry, engineers ultimately (still) control the fate of a technical writer’s job. He or she has control of the budget, so the decisions (no matter how skewed and unrealistic they may be) are in the hands of an engineer. Also, the new software industry has become open-source, so it is important to understand how that affects job opportunities. Many out-of-work technical content developers do not possess knowledge of the new programming platforms; this just closes the gap even more between younger and older candidates.

Due to a talented younger generation’s skill set improving, hiring teams will seek candidates that have similar values, attributes, and unfortunately age group as well. A 30-year old hiring manager will often hire a 25-year old employee over a 45-year old employee assuming that the younger candidate will be able to work long hours, work weekends, go on company ski trips, go out to the bars after work, and attend other work ‘bonding’ activities. Currently, hiring teams prefer a spry, younger candidate versus a seasoned writer.

It is not uncommon for a hiring manager to have no clue what a technical writer does, or what he or she needs a technical writer for, so how is he or she supposed to find a good technical writer? Recruiters help out in this instance, helping link potential candidates for job openings with the technical companies. Older candidates must make themselves stand out and be persistent when seeking a job opportunity, though, due to ageism.

Another common reason that companies are averse to hiring an older candidate is health insurance. An older person is perceived to be more likely to get sick, and therefore the employee would be less productive for the company’s bottom-line. Older candidates also can be perceived by hiring teams as more rigid and less likely to abide by all of the companies desired techniques or methods. Companies are looking for a candidate that is “more pliable and more cooperative.” The employer prefers someone who will work on-site, someone who will learn and adapt to company policies and strategies, and someone who will “go with the flow,” as Andrew Davis likes to put it.

Before a candidate can even get started with a company, the interview process must take place, and you have to be extraordinary to get a job opportunity. Obviously, it is quite difficult for someone to interview for a company, have it go well, but not have a job offer at the end of the process. Often an older candidate will have a good resume and think that an interview went really well, but later will hear from the employer generic excuses such as “you have too much experience” or “you are a flight risk” or “you are over-qualified.”

The employer uses these aforementioned trite justifications instead of admitting a “politically incorrect” reality; the employer prefers a younger (and cheaper) employee that will work as a peer within the framework of the company team. Obviously the employer cannot use ageism as a legal reason for not hiring an older candidate, so the above-mentioned clichés are common things that employers/ interviewers will say when deciding not to hire an older candidate.

To combat all of the negative predisposed attitudes that many hiring teams may have, an older candidate must act proactively and assertively when a job opportunity arises. The older candidate must stress his or her efficiency, quality, focus and self-awareness. Nothing replaces experience, so experience and wisdom are definitely strong points that an older candidate must utilize as these are clear advantages over younger candidates. Older candidate can also point out the fact that he or she “has been there before,” so his or her work will be more consistent in the face of adversity than the younger generation. Also, having experience in the field gives the older candidate a “sixth sense” for what users need and a good idea of what works and what doesn’t based on his or her prior professional experiences.

Probably one of the most valuable attributes that older candidates possess over younger candidates is self-awareness. Self-awareness is built through experiences and observation of your surroundings, so you become increasing self-aware as you age. Older candidates understand their own strengths and own weaknesses, and are not afraid to seek help when they know that they are out of their element.

Older candidates must stress these attributes during an interview process in order to distinguish themselves “ahead of or above the crowd.” Andrew Davis describes the best way to handle the process, “Be the one that commands the interview. . . On the phone interview explain your skills and assets. . .Offer real-world references and send samples to impress them [employer/interviewer].” Andrew also said it best in this quote, “Ask what the problem [that the company has] is… Tell them ‘this is what I can do for you and I am the right person for the job’.” . . You need to seize the opportunity and make the interviewer think to him or herself, “If I do not hire this person I am making a mistake.”

Andrew Davis concluded his presentation by letting some members attending the meeting to share personal success or not so successful stories. One member described a very unfortunate story, as he was laid off on his 65th birthday. Companies are ruthless nowadays. Even though there were some bad moments, there were some positive success stories as well. A woman mentioned that she was able to find work during her 50’s, and mentioned that two friends that also did technical content development found work when they were in their 60’s. Another member said that the STC has been very helpful when it comes to finding employment and possible opportunities. The National STC website helped a member obtain a contract position at a start-up and the engineer project manager of the start-up said, “The best place to find a technical writer is the STC [Society for Technical Communications].”

Andrew shared a few more ideas and answered a few more questions before the meeting ended. When asked about social media “Start with Linked-In. It’s where all the hiring managers start. They try to do it without my help, thinking that we are all working from the same pool. . . In the beginning it [social media as recruiting tool] is cheaper than a recruiter, but costly mistakes in the near future are more likely to happen.” Andrew also says that you are wasting your time if you are trying to use Facebook or Twitter to look for job opportunities. Linked-In is the only social media platform that is currently ‘legitimate’ from the employers’ perspective.

Andrew wrapped up his presentation with his contact information, which is detailed below for reference. Also, one of my personal favorite quotes of the night was after a member had one of the last questions of the night. She asked Andrew, “Why do companies come to you looking for help to find technical writers/ technical content developers.” Andrew replied, “They [the companies in need of help] come to me when their backs are against the wall and don’t know what else to do. . .”

Contact Andrew at www.linkedin.com/in/synergistech.

 

February 2014 Meeting Discussion: A Case Study of Simplified Technical English for Translation

Presented by Nathaniel Lim, and reviewed by Louise Galindo

Nathaniel Lim is a senior technical writer who helped to develop a subset of Simplified Technical English for Electra, called EASE- Electra Approved Simplified English. He gave a lively and informative talk about the project, but also shared with us a number of the guidelines that his company uses, which are guidelines that speak to all technical communicators who are interested in STE and topic-based writing.

My team worked with the following sentence: Rewrite these sentences. (My team’s rewrites are at the end of the article.)

 

  • Users can filter by certain options in the software. Using a filter narrows the option list.

 
This project started because Electra wanted to manage translation costs by reducing word count by 30%. The company translates its content to 25 languages so the need to reduce costs was evident. Nathaniel based the vocabulary that Electra uses on the larger STE approved vocabulary. The writers had two days of training to learn how to use the approved vocabulary. It was pretty impressive to hear about that commitment to training.

The writers have a list of approved and nonapproved verbs. They also have text limits that include:

  • Procedure sentence: 20 word maximum. (Tough.)
  • Descriptive sentence: 25 word maximum. (Tougher.)
  • Paragraph: 6 sentences maximum. (Not bad!)

In addition, he presented some of the 58 writing rules that writers are required to learn:

  • One word has one meaning and is a verb or a noun, but not both.
  • Delete courtesy words: welcome, please, thank you, and so on.
  • Do not make noun clusters of more than three nouns.
  • No semicolons (;).
  • No possessives.
  • Do not use present participle, for example, You are adjusting…
  • Be specific in a warning or caution. Make sure that the reason for why it is a warning or caution is clear.

As a technical editor, Nathaniel’s rules were music to my ears. Simplify, simplify, simplify!

Nathaniel pointed out that how you write a sentence is based on whether it is a concept/description or a step in a task. The sentences at the beginning of this article might be a step or they might be a concept.

Here are ways to rewrite the two sentences. Regardless of how you rewrite these, the idea that writing itself is different depending on whether you have a step or a concept is important to understand.

 

  • Concept/Description: A filter lets you decrease the options.
  • Procedure: Use (Create?) a filter to decrease the list of options.

 
Nathaniel is a wonderful presenter, and in this case, he gave terrific takeaways that re-enforce guidelines for STE, topic-based writing, and translation.

Louise Galindo is the Senior Technical Editor at Splunk, Inc. She is also the Co-Manager for the STC Technical Editing SIG. (We are looking for a co-manager.) Louise is also an Instructor at UC Berkeley Extension, where she teaches Technical Communication I and II.

October 2014 Meeting Discussion: Managing Tech Comm Projects in Any Environment

Presented by Sharon Burton, and reviewed by Jay Martin

Plan your projects, define the way your success is measured, and heed the other friendly advice from Sharon Burton, an STC Associate Fellow and consultant.

Promote Tech Comm

Burton began with some advice she tells her clients: It is easier to sell to prior buyers. Returning customers are a better source of revenue. Documentation adds value, post-sale, when it helps customers use the product. Documentation helps branding.

Some companies need to be reminded that people read documentation, Burton said. Companies are not thinking of documentation as a place their customers are. Companies are not using technical content in their social media.

Customers discuss a product in social media, user forums, blogs, wikis, and other “ad hoc content,” as Burton calls it. Technical communicators are increasingly being asked to be responsible for user-generated content in some manner. Customers are remarkably tolerant of ad hoc content, Burton said. They understand that content created by a company is the source of accuracy for a company’s product.

Define Success

Burton’s main message for us as technical communicators was to set expectations. Write the definition of success for documentation. Success can mean on time, within budget, as stated, and accurate. Success can be to reduce support costs, engage and increase return customers, and “fifty other ways to define success,” said Burton.

If a company has a metric for development or marketing projects, then apply the same metric to documentation. Refine the metric with each deliverable. Describe your measures of success to people at the company, then ask for additional measures. In the process of soliciting opinions, you will also be spreading the word.

Evangelize your definition of success, Burton said. Expose how documentation happens, which is a mystery at many companies. Use status reports, planning documents, staff meetings, and chats in the lunchroom. Announce in the corporate newsletter, “We released x documents in y languages.”

Estimate Carefully

Consider levels of work in your definition of successful documentation and in your planning. Burton suggested that a first level is spell-checked only, with no examples. Second level is verified against the software, copyedited, and indexed. Third level is structured and optimized for readability, comprehension, and localization.

In your per page estimate, include time to manage, research, write, edit, illustrate, proofread, translate, prepare for publication, attend project meetings, and attend review sessions. If you lack prior examples, then start with Burton’s metrics: User guide, 2 hours per page. Training guide, 30 hours per hour of training. Context-sensitive help, 2 hours per topic. Content to multi-publish, 2 hours per topic. Editing community-generated content, 1 hour per 500 words.

A common error is to set the earliest possible date, or a little after it, as the completion date. Another error is to set a completion date because it will please management.

Enjoy Complexity

Evaluating complexity is our job, said Burton. External factors to evaluate include product stability, information availability, prototype availability, subject matter expert availability, and effectiveness of reviews. Internal factors include our technical experience, team cohesion, writing and document design, and audience understanding. One company that Burton helped had never evaluated its audience.

We work in product development environments that differ. A waterfall environment is iterative, with extensive planning and multiple phases. The process, stable but slow, is used by government and hardware companies. By contrast, an agile environment is managed and planned in sprints of two weeks, usually. The process, driven by customer stories, is used by software companies.

Multichannel publishing, formerly called single source, is our deliverable. Our documents appear as hard copy, PDF files, online help, offline help, e-books, smart phones and devices, tablets, HTML5, multiple languages, and device-sniffing content.

Reconsider Regularly

The book metaphor has become too expensive for companies and technical communicators, according to Burton. Books lock content into files no smaller than chapters. “You can’t reuse what you can’t get to,” said Burton. She tells companies to consider new tools and technologies. “Check in with your decisions every two years.”

Burton is happy that technical communication presents new problems to solve. The members at the meeting agreed with Burton’s message: Planning has changed, but we still need to plan.

Jay Martin is the technical editor at EMCOR Energy Services.

September 2013 Meeting Discussion: Converting FrameMaker Content to DITA

Presented by Scott Prentice, and reviewed by Rebecca Firestone

This presentation by Scott Prentice, founder of Leximation, Inc., http://leximation.com focused on the detailed steps, and pitfalls, of converting unstructured FrameMaker books into structured FrameMaker, and from there all the way to XML/DITA. Prentice has been doing this for over 20 years and has developed his own methodology, which he kindly shared with us, running his Adobe FrameMaker 11 inside VMWare on a Macintosh. (He says it works better than on a PC as long as the Mac has 8 GB of RAM.)

Takeaways

  • Frame to DITA conversion is NOT a simple, one-step process: it’s labor-intensive and requires several sets of tools.
  • Many features of the original Frame books may be lost, especially if you’re using multiple text flows and frames with multiple graphics and text callouts.
  • Any irregularities in the original Frame files will have to be corrected, along with extensive content rewrites to better fit the DITA model. In other words, it’s not for the faint of heart.
  • After conversion, you don’t have to go through it again for the same book–future content revisions are made within the new XML files. (If you open an XML file in FrameMaker, you’re using the “Structured FM” interface, but you’re actually working on XML files.)

Let’s see if I can remember the gory details.

There are actually several methodologies besides the “Conversion Table method” that Prentice demonstrated.Frame to DITA Options

  • Conversion Tables – Lots of short steps, with some automation, a lot of manual fixes at each step, very iterative. Different tools needed at each step, either scripting tools or FrameMaker plug-ins. Benefits are the ability to fix structural problems at each step before going on to the next.
  • Mif2Go – More of a one-step process, but doesn’t have any intermediate points to fix things. “Best if content is rock-solid,” emphasized Prentice.
  • Stilo Migrate – A cloud-based tool that charges by the amount of content converted.
  • WebWorks – Possible, but you need customization and templates, which WebWorks discourages.
  • Consultants – For example, Prentice and Leximation, or others. This might be a good option if you have only a few books to convert.
  • Copy/Paste – Not such a silly idea, since you have to do a lot of rewriting anyway. Not as fast.

So why do we need all these intermediate steps? Well, content is rarely that clean. (Huh. I don’t know about you, but MY content is always perfect…)

Prentice recommended the book Structured Application Developer’s Guide and Reference from Adobe, which is actually two books now: one for Guide and one for Reference. (Not available in print.)

Conversion Table. This is where you map Frame styles to DITA elements, and then “wrap” the elements into sub-assemblies to create ordered lists and groupings of elements. Prentice did a lot to de-mystify this beast, although an hour won’t make anyone an expert.

Content Analysis. Prentice didn’t discuss this at length, but I think this is where a consultant would come in handy, to expedite and guide in this part of the task. Every bit of content, and how it’s structured, must be sanitized with a fine-toothed comb. Whatever you come up with from this step influences the Conversion Table. Getting this part right will save you time later on. Try to have a test file in unstructured Frame that contains every single style tag and content type that you want to have in your converted files.

Prentice didn’t try to gloss over the real work involved in Frame to DITA conversion.

Style overrides will come back to haunt you.Pitfalls

  • Use paragraph and character tags consistently, for one type of content. Don’t use a Figure Caption tag for something that isn’t actually a figure caption.
  • Only the main text flow will export. (I interpret this to mean that anything with a fancy page layout like a newsletter with multiple “continued” flows for several articles is not going to come across well.)
  • Multiple objects and graphics within a single frame are merged. I wish we’d had more time to see this, since it would be interesting to review the resulting image quality.
  • Tabs and line breaks are typically lost, although there are ways to preserve line breaks.
  • Conditional text applied within a paragraph will have problems. Apply C-text at the paragraph level only. May require additional scripting or tools.
  • Cross-references need scripting to work properly, and may need to be gimmicked.
  • Variables turn into entities.
  • Tables are especially fun. Titles end up in the wrong place, and that’s only the start.
  • Each topic needs a unique identifier, which Frame does not handle well for DITA. Requires scripting.
  • Don’t have two subsections named “Overview” in different chapters in your book if you plan to create the XML file names from the headings.
  • Expect a lot of post-processing. Not only cross-references, but image references may need conversion.

Clean up Frame files. Re-apply style tags and rewrite content.Conversion process

  1. Apply conversion tables to Frame book, creating structured Frame files.
  2. Import EDD and a template into structured Frame files and review the resulting redlines. Fix problems.
  3. Clean up structured Frame files using FrameSLT or other similar tool. You will spend a lot of time here.
  4. Export to XML, making one XML file per chapter.
  5. Perform additional cleanup via XSL to “shred” this monster XML into separate files, or use a tool to do the shredding for you.
  6. Open all this XML in structured Frame to validate. Alternatively, you can run it through something like DITA Open Toolkit and “see where it blows up.”

If the above seems too full of jargon, try reading one of Prentice’s blog posts like this one: http://blog.leximation.com/2012/01/framemaker-edd-template-rules-%E2%80%93-what-is-all-that-and-how-does-it-benefit-me/

The rest of the talk was pure demo. Being able to see the results at each step was very useful. It was a bit like a programmer’s walkthrough. Prentice really knows the “gotchas”. It seemed that his process was somewhat idiosyncratic, although I could say the same of a lot of what I do, too. If you want perfect control, you end up tweaking just about everything. A cynical person might suggest that he’s making the process seem harder than it needs to be so that people will hire him instead of trying to do it all themselves – well, I’m all for getting expert help if it means the project actually gets done, and I get to keep my sanity.

So, Should You Drink the Kool-Aid?

I’d probably hire a consultant like Prentice to get me over the hump and act as a coach during the conversion period, but would also try to acquire that expertise myself as we went along. Organizations that don’t have an in-house writer might need to hire an additional contractor who’s already familiar with XML conversion to do a lot of the grunt work.

If we’d had more time, I would have liked to explore a larger question, namely: When is it really worth it to go through all this? What staffing levels and timeframes are realistic to achieve a successful migration? What else is out there? There was a talk a few weeks ago at STC-Berkeley where the presenter said “Oh sure, a solo writer can do it all, without previous experience. . .” Really? I can’t see that happening if the writer is also simultaneously responsible for developing new content, in constant meetings with product developers, etc. . . I began to question the value of the entire exercise, but it’s probably only a matter of time before we’ll all have to start moving in this new direction.

Rebecca Firestone began tech writing in 1988 in Washington, D.C. Highlights include OR/MS topics and software documentation, including telecom/wireless billing and contract work throughout the Bay Area. In addition, Rebecca did a 2-year stint as a software trainer, and several years of design blogging for local Bay Area architects. Outside interests include yoga, Middle Eastern music and dance, circus arts, and fitness. She is currently employed as a Senior Technical Writer at Zep Solar, Inc. in San Rafael, CA.