All posts by Michael Meyer

Our June 2012 Meeting: “Hands on with EPUBs – Mini-Workshop,” with Scott Prentice

Authoring applications, Meetings, STC NorthBay Blog, Uncategorized

Those wise and fortunate enough to attend this meeting left appreciating a learning experience one likely would have to travel to an STC conference to obtain. Again, Scott Prentice shared his considerable depth of understanding of the technical details underlying the words we read on the surface, and in the case of EPUB, we got to look under the hood and see how the various components of a document are related and stitched together.

(For the what, why, and how of EPUB — yes, ALLCAPS are back in fashion now — see Scott’s previous presentation.)

For the deconstruction process, we downloaded an ebook of one of my favorite authors, one E. A. Poe, and proceeded to deconstruct it with the oXygen XML editor. (Ever see the decoder table in “The Gold Bug” in XML?) A trial license is free for a month, and anyone interested in seeing how an EPUB document is constructed is encouraged to do the same.

With more and more existing information likely to be repurposed for mobile appliances, it will not hurt to become more familiar with this evolving publishing technology, perhaps the hottest thing since movable type. Standards are still evolving, with the powerful HTML5 standard still more or less on the horizon, and EPUB2 more reliable than EPUB 3. (You can download for free some great resource ebooks from oreilly.com: look for “What is EPUB3” and “HTML5 for Publishers.” You can inspect the mysterious workings of these well-formed publications with oXygen, or even the free Sigil, which is also a ebook good reader.

As for ebook readers, Scott provides a good list in his meeting notes. There are many other goodies in those slides, so take a look. If you are interested in this growing area of doc expertise, Scott will be glad to explain.

Our May 2012 Meeting: “Emerging Roles and Hot Markets for Tomorrow’s Tech Writers,” with Andrew Davis

Employment, Meetings, STC NorthBay Blog, Uncategorized

With tight job markets, unique skills requirements, and risk-averse hiring managers, finding work in the world of technical communications is not what it used to be . . . no more mirror test.

However, the world of contract and contract-to-hire can still be rewarding for individuals who have precisely what a company (often a young one) needs with respect to skills (often intangible), but also with respect to attitudes that often go beyond those required by old-school corporations. In short, “skills” and “experience” are not enough — at least in the common use of those terms. As a major recruiter for Content Rules, Andrew Davis has accumulated a lot of understanding of the contemporary job market for technical communications skills.

Desirable Intangible Skills/Experience

What are those intangibles?

  • Do you understand the business goals and business model of the hiring company?
  • Do you have entrepreneurial experience (which comes in handy in a startup environment)?
  • For a given product or service, do you understand the audience’s context, needs, and priorities?
  • Can you visualize and design customized content deliverables?
  • Do you understand what it takes to translate/localize content successfully and at least cost?
  • Are you experienced in making a business case for content initiatives?
  • Do you understand the latest tools and can you demonstrate their use?
  • Do you have project management and consensus-building skills (which also come in handy in a startup environment)?

Desirable Empirical Skills/Experience

In the area of contemporary tools, Andrew lists the following:

  • Hot are HTML5, EPUB3, or iBooks Author: In a multiplatform environment, eBook conversion and delivery can be paramount, through XML, XSL, XSLT, XSL-FO, DITA, DocBook, structured authoring tools such as Arbortext Editor (formerly “Epic”) and XMetaL Author, and (to a much lesser extent) Structured FrameMaker, Author-it, and MadCap Flare.
  • Of particular importance is video production (iMovie, etc.) or screencasting experience (Captivate, Articulate, etc.)
  • Can you implement a Wiki, after convincing an employer of the value of one?
  • Have you demonstrated skills in interface/user-experience (UX) design, especially for mobile applications?

Andrew lists what is not, and what is not, with degrees of temperature in between.

Hot Industry Niches for SF Bay Area Content Developers

This is what employers are willing to pay for, at least for today:

  • Data analytics
  • IP security
  • Big data (Hadoop, MapReduce, NoSQL, etc.)
  • Mobile/GIS (iOS, Android)
  • SaaS-ified apps
  • Data center optimization/virtualization/cloud
  • Open source
  • Social
  • Advertising
  • Games/entertainment

Tepid Niches

The following areas are not suffering, but they are just not as hot:

  • SQL/data warehousing/business intelligence
  • Enterprise applications (non-SaaS)
  • Search
  • Development tools
  • Content translation/localization/internationalization technology
  • Medical devices
  • Biotech/pharma
  • Storage (SAN/NAS technology)
  • Networking (including videoconferencing) – noncloud

Not-so-Hot Niches

Here we can see how the world we used to know so well has changed:

  • Finance/insurance
  • CRM
  • Semiconductors/EDA
  • PCs, tablets, smartphones (hardware)
  • Peripherals
  • Manufacturing (most)
  • Government
  • Healthcare
  • Law
  • Utilities
  • Infrastructure (transportation, etc.)
  • Education
  • Publishing
  • Graphics (hardware, software)
  • Clean/green tech

Consistently Hot Tech Comm Roles

If you have demonstrated skills in the following areas, you should be fine until the next paradigm shift:

  • Developer-oriented content creation (API references, developer tutorials)
  • Video (scripting, creation) – not just scriptwriting, podcasting, blogging
  • UX design
  • Structured content design/migration (part of “content strategist” work)

Not-so-Hot TC Roles

And here are the old-school skills that you may have, but that employers are not so interested in:

  • Publications manager
  • Editor
  • Proofreader, indexer, formatter
  • End-user doc (for consumers and nontechnical audiences)
  • System/network administration doc
  • Proposal writer
  • Business analyst
  • Trainer (nontechnical, but in recent years also the technical variant)
  • Instructional designer (nontechnical)

How to Get Hot (a One-Page Primer)

Here are Andrew’s tips for success in the current talent marketplace:

  • Avoid academe (with few exceptions, schools are out of date, and more degrees and certificates are not a substitute for specialized experience).
  • Download (and immerse yourself in) trial versions of your niche’s tools (the entry cost is cheap).
  • Participate in open-source projects (this will take a bit of looking around, but the rewards are there).
  • Build a portfolio online and link it to your LinkedIn profile. The portfolio demonstrates initiative, mastery of tools, and subject-matter awareness/interest. Make it easy for your target audience to get the info it wants.
  • Study how others do it, then emulate the best.
  • Intern or subcontract – or just volunteer (for a written reference).
  • Conduct informational interviews (solicited through LinkedIn).
  • Sell your services to the young companies, who really need your experience.
  • Network! Do it in person through meetups (Andrew likes svnewtech a lot), and also use LinkedIn and corporate alumni networks (and even STC!).

Upsell Your Core TC Skills

In marketese, nothing beats repackaging what you have to offer so that it rings with currency in the ear of the beholder. Could you find yourself wearing the following hot terms?

  • Content Strategist (cf. Information Architect)
  • Content Marketer
  • Community Liaison
  • Corporate Storyteller
  • Toolsmith (for wikis, structured content authoring/migrations, mobile content, content management, etc.)
    User Experience (UX) Designer (not UX Engineer)
  • Terminology Manager
  • User Assistance (UA) Expert
  • Content Manager (SharePoint administrator, process/workflow optimizer)
  • SEO Expert
  • Niche Analyst/Blogger/Tech Gadfly/Content Curator
  • Conference Organizer
  • Ghost Tweeter
  • Demo Builder (involves scriptwriting, animation, and marketing)

And Try Successor Careers

Below are all “titles” that you may be able to wear after your years of service — which was not just about “docs,” was it?

  • Business Analyst
  • Project Manager
  • Program Manager
  • Engagement Manager
  • Marketing Communications Manager
  • Corporate Communications Manager
  • Localization Manager
  • Executive Communicator (speechwriting, spokesperson work)
  • Technical Sales (including recruiting)

(As for management, Andrew cautions, it can often be a trap, so wear two hats and keep the managerial skills — but be able to produce content as well.)

Following the 2001 tech wreck, Andrew tracked the fields into which a number of experienced technical communicators moved at “Career Paths for Tired Tech Writers” (http://www.synergistech.com/career-paths.shtml), and he would be happy to connect anyone interested in reaching out to these individuals.

Just be ready for the next paradigm shift, and if you find work that works, take it. (For a copy of Andrew’s slides, see http://www.stc-northbay.org/meetings/presentations/pres_2012-05_Emerging_Roles_and_Hot_Markets_for_Tomorrows_Tech_Writers.ppt).

Andrew thrives on inquiries and feedback, so give him a call:

Andrew Davis, recruiter
408-395-8178 ext. 105
andrewd@contentrules.com
www.contentrules.com/jobs

Our March 2012 Meeting: “Agile Documentation (Hi, Honey, I joined a cult!)”

Meetings, STC NorthBay Blog, Training, Uncategorized

Fundamentals of Agile Development
Mike Ziegenhagen, a technical writer and tech pubs manager in the software business for more than 18 years, has also specialized in documenting virtual worlds. One virtual world you may be familiar with is the one that “relates” (read “force fits”) product specifications to actual products. If you have ever suffered from the disconnect between fantasy specs and real deliverables, you will appreciate how the Agile process keeps a tight rein on development, making sure that each feature works properly before subsequent features are added — all executed in cycles of generally a couple of weeks at a time. The Agile approach embodies the principal of iterative and incremental development: Never get ahead of yourself, and keep it real. While “Agile Documentation” is not yet a topic on Wikipedia, it is not hard to extrapolate from stepwise development to stepwise documentation.

Mike spoke from experience. For the past two years he’s worked with a team of writers in a large enterprise software company that embraced Agile software development from the top management team down. (Without proper buy-in and support at the highest levels, it is hard to realize the benefits of this approach.)

Some Basic Principles
An Agile Manifesto lists four fundamental priorities. Favor . . .

  • Individuals and interactions over Processes and tools
  • Working software over Comprehensive documentation
  • Customer collaboration over Contract management
  • Responding to change over Following a plan

    • There remains value in the functions on the right, but these should never dominate.

    Real reality, not the virtual variety, is key. Unlike the all-to-familiar MS Project approach, where 100-page best-laid plans of mice and men soon go stale, Agile requires daily truth-telling sessions in meat space. Each participant stands and briefly addresses three questions: What have you done since yesterday (in an interval known as a “sprint”), what are you doing today , and are you being blocked from what you have to do? A series of sprints comprises a release for the multiple teams, called a scrum (yes, development can be bruising like rugby). In the sport, a scrum restarts the game after a minor infraction — a fair analogy. In development, a Scrum Master ensures that progress is made at each sprint truth-telling session. At the top of the process is the Product Owner — who is closest to the “first customer” and knows precisely what a potential buyer needs, wants, and is willing to pay for. All other features can come after the basic functionality of the product is rock solid. What a concept!

    And the benefits?

  • Avoid the “spec monster” approach, which creates bloatware or (worse yet!) phantomware.
  • Avoid turning the prototype into a product (seen that fantasy before?).
  • Meet changing needs and markets easily, simply by adding or removing iterations (you can always catch up later if you need to).
  • Address bugs early and often, preventing unplanned delays in product releases.

    • Agile Documentation
    Until someone writes the Agile Documentation page on Wikipedia, here are the principles Mike has arrived at from his experience as a writer involved in the Agile process:

  • Don’t sweat providing documentation for discoverable tasks. (Click OK already!)
  • It is virtuous to keep things simple, but only if you provide enough information for the user to accomplish a task.
  • Provide simple documentation for complex tasks (keeping in mind the principle above).
  • Don’t make documentation more than it deserves to be. Documentation is part of the process of users doing their work; it is not the process (communicate rather than “document”).
  • Write the documentation you would like to read. (What a concept!)
  • Follow the principle of Occam’s razor: Keep things as simple as possible, but no simpler (see above).
  • Build documents from the center outward, as time allows. Use the software, take notes, flesh it out. Do not write the outline and fill it in with content! (cf. “fantasy specs” above)

    • But Wait, There’s More!

    This should be enough to get you interested and motivated to learn more about Agile. And what better resource for that than the excellent slides you may have missed if you were not at our meeting. Many who attended will have some thoughtful insights to take back to the workplace.

    So dig a bit and see what Agile could do for you!

    Call for Chapter Officers

    STC NorthBay Blog

    Our chapter meetings may not be SRO, but we still provide a service to the North Bay technical documentation community — and we invite your participation in chapter roles. As long as you are an STC member and are able to attend regular chapter meetings (you do not need to be a NorthBay Chapter member), please contact president@stc-northbay.org from now through the last day of November if you would like to take on the role of president, vice president, treasurer, or web master.

    Topic-Based Authoring with Linda Urban

    STC NorthBay Blog

    STC Sacramento is presenting the following workshop:

    Saturday October 22, 2011
    9 AM to 5 PM

    Topic-based authoring is a technique for writing content as discrete, stand-alone pieces (“topics”) that can be combined and reused in different ways. The topic-based approach has been getting a lot of attention recently because it is an integral part of DITA (the Darwin Information Typing Architecture) and other XML-based solutions. However, topic-based authoring has actually been around for quite some time, and does not require DITA or XML. Using a topic-based approach can improve consistency and usability of information, and can make it easier to reuse topics in different contexts. It can also simplify maintenance, speed up the review process, and facilitate shared authoring.

    For additional details and registration:
    http://www.stcsacramento.org/Misc_docs/TopicBasedAuthoring.htm

    Our July 2011 Meeting: “ePub: What, Why, and How?” with Scott Prentice

    Authoring applications, Meetings, STC NorthBay Blog, UA (User Assistance)

    Scott Prentice, chapter webmeister, president of Leximation, and all-around FrameMaker guru, brought us up to date regarding the latest developments in electronic book publication standards. With the current proliferation of portable Internet devices, the savvy tech doc specialist may want to be aware of the issues involved in converting source documents to those that are readable, usable, and attractive on small screens.

    The standard is “EPUB,” which Scott prefers to render as “ePub.” It is just another of many eBook formats, such as MOBI, DJVU, PDF, HTML, and TXT, that has evolved through time to meet user needs. ePub specifies the format and structure of the deliverable, much like a CHM, HLP, PDF, or HTML file does, and it requires both an application and a device to render the content for viewing. The underlying format is XHTML and CSS, with all components, such as content, images, and navigation, invoked from a single header file. Digital rights management (DRM) may also be included. The real wonder of it all is that content flows to fit the screen of the device on which it resides (to varying degrees of quality, as we will see later).

    The ePub specification is maintained by the International Digital Publishing Forum (IDPF), and ePub 2.0 became an official standard in September 2007. (The original Open eBook standard of 1999 was actually developed for audio files and accessibility.) ePub 2.0.1 is the current stable build, and there is already a 3.0 draft. ePub comprises the following specifications:

    Open Publication Structure (OPS): a standard for representing the content of electronic publications

    Open Packaging Format (OPF): defines the structure and semantics as well as the mechanism by which OPS components are related

    Open Container Format (OCF): (Seriously, Officer! the ePub was closed!) defines the mechanism by which all components of an electronic publication are packaged into a single deliverable (a ZIP archive)

    So what are the many advantages, and why care?

    The number of dedicated eBook readers is expected to exceed 11 million units by the end of this year, and the ePub format is supported by all readers and applications except the Kindle. A particular advantage of the format, in an age of vanishing trees, is that it is well suited to content that has limited life span — such as those 15-lb. programming manuals that are soooo last week. Rendered by a variety of conversion tools, ePub format works best for linear content, although reference material can use this approach as well.

    It’s relatively cheap to provide instant gratification with this format. The user can search, add bookmarks, and annotations, and the content is very portable. But beware the downsides.

    Tables more than a couple of columns wide can be disastrous on small screens. Links do not always work. Compliance with the standard varies highly, with no approach fully compliant. Indexes are not supported (although it is possible to create one as a page with links).

    And as we noted earlier, renditions vary greatly (and can be truly extraordinary). Scott presented views of three different readers for the same content, and the differences were striking. As you will need tools (hand rendering is possible but not recommended), be sure to test drive a variety of applications to see which does the best job for your target devices. Scott presented an example of a specification document that he had converted, and it was very attractive and usable on both an iPhone and an iPad.

    Enough for this overview. Now see the presentation summary that Scott provided and do your own exploration. Then head to the ePub for an ePint and let it all sink in.

    Our March 2011 Meeting: Optimizing Your Portfolio, with Andrew Davis

    Employment, Meetings, STC NorthBay Blog

    Andrew Davis, formerly principal of Synergistech Communications and now a recruiter for Content Rules (formerly Oak Hill Corporation), provided valuable insights (both live and remotely) at our March 2011 meeting. A true champion of the candidate, he reads a lot of job descriptions and resumes, and made clear that a great portfolio (and approach) is your best chance of landing a job in technical communications in the current environment (which, perhaps surprisingly, is becoming more and more favorable to the job seeker).

    You can’t just have a resume anymore; you need hard evidence to back up what is on it:

    • Provide proof that you understand your audience, really know your tools, and can organize, write and deliver.
    • Have you mastered the three types of software documentation content (procedural, conceptual, reference)?
    • Have you mastered the three basic delivery types (linear prose, task-based help, instruction)?
    • Have you developed concrete doc plans?
    • Have you demonstrated a master of doc organization (TOC, concepts, procedures, reference, glossary, and even the index?)

    Well, have you?

    So what sells in the current market?

    • Clean, friendly prose with the end user clearly in mind
    • Illustrations, useful screen shots
    • Code examples
    • Complete instructions
    • Use cases and implementation scenarios
    • Troubleshooting

    The audiences for each of the above are different, but the aspiring applicant who can demonstrate mastery of most of the above stands the best chance of success.

    And when you are on the spot in front of your prospective employer, what wins?

    • An effective presentation, with information that is accessible, relevant, and in a meaningful context: what were the conditions, constraints, and strengths and weaknesses (yes, those) in how you succeeded — or not?
    • How did you approach similar challenges?
    • What did you deliver and why?
    • What did you learn?
    • How did you succeed in the end?
    • What was your role in development?
    • What were all the circumstances you encountered and how did you deal with them?
    • What would you do differently next time?

    In short, be the best narrator you can, and leave nothing to chance.

    So how does one deliver success stories these days? Many use the ubiquitous and affordable LinkedIn (which also hosts a “Creative Portfolio Display” section). Or develop a private website in which to hang your best work with a narrative. For the transfer of large files to your prospective employer, use box.net. Or use private directories (password protected, of course) and even (duh) email (for files that are not too large).

    But, you say, all my examples are proprietary? Well, if you don’t deliver something, employers will assume you are bluffing if you just say, “Sorry, I have great stuff — just can’t show it.”

    Too bad for you.

    So how do you deal with the sticky issue of proprietary information? Here are Andrew’s suggestions, in increasing order of difficulty:

    • Ask the prospective employer to sign a nondisclosure agreement (NDA). Companies ask others to do that all the time, so don’t be shy. It shows you are a mature negotiator as well as a respector of (eventually their) intellectual property rights.
    • Neuter the content. Do search and replace on a variety of key words.
    • Redact key sections, as Acrobat Pro allows (Acrobat Standard may do this too). However, even though you can black out words and lines, be sure to lock the file against further edits!
    • Ask your ex (or currrent) boss for permission. Your judgment call here.
    • Contact your current (or previous) legal department for permission. Your judgment call here.
    • Ask for the names, addresses, and SSANs or the reviewing parties. Your judgment call here. (Success stories would be interesting to hear.)

    In the absence of success in any of the above, or even if you have no current examples of the types of documents you would like to write, you can always take a public-domain document or public-domain information and rewrite and reorganize it, demonstrating your clear command of information management. Demonstrate your command of a technical subject area, as well as of your understanding of your audience.

    Finally, avoid the classic “I am such a quick study, just teach me anything I need to know and I will learn it.” Well, that does not work in the current environment. No employer wants to hire a liability, and your inexperience should not end up their problem. Hiring managers are terrified to make a wrong hiring decision, and will instinctively minimize their risk any way they can.

    So demonstrate the following with concrete examples: initiative, motivation, a master of subject matter sufficient for the task, an ability to overcome gaps in information and other challenges.  Most of all, make it crystal clear that you will be a good investment.

    It is as simple as that.

    For additional information, don’t hesitate to contact Andrew at andrewd@contentrules.com. Your success and his are intertwined.

    Our January 25, 2011 Meeting: “Write More, Write Less” with Joe Welinske

    STC NorthBay Blog

    Joe Welinske has been a technical writer since 1984, and one of his first documents was a comic book. In four colors. For plumbers. To put in a hip pocket. Why make plumbers carry around a standard size tech doc to tell them how fit pipe when something much smaller would do? The manual was a hit, and an great illustration of the practicality tech doc writers often overlook when tasked with user assistance, or UA. (His website is www.writersua.com.)

    Joe currently crafts user interfaces for iPhone apps and scripts YouTube videos to support other mobile apps, but he wisely counsels us to remember there is more to our trade than tools and technology. Having been recently in a hurricane in the Caribbean, he  showed examples of old-school journalistic style (on CNN’s website) that presented just the weather information he was curious about and in the correct order and proportion. Keep your key ideas up front, save the details for later, and do not overwrite so that you bury a good message in clutter — just simple, classic journalistic principles.

    He cites Jakob Nielsen on good web design (see www.useit.com), and how readers do not approach web pages linearly. Here again, use the inverted pyramid approach from journalism school (you did take some journalism, right?), and lead with the conclusion if you want to be efficient and make your readers happy. Use bullets, meaningful subheads, one basic idea per paragraph, and toss unnecessary words. Some of us, like Dickens, may get paid by the word, but odds are that every unnecessary word is just a burden in your organization, from first draft through ongoing maintenance and costly localization.

    Says Joe, “UA will become most effective when we spend twice as much time writing half as many words.”

    Anyone wishing to polish up UA skills would do well to consider the Conference for Software User Assistance, to be held March 13 through 16, 2011, in Long Beach, Calif. The conference focuses on “developing the best possible user experience for all types of software applications through well-designed interfaces and helpful and accessible support information.”  In short, “Better UX through Better UA.” For details, see www.writersua.com/conference.

    January 22, 2011: Annual Berkeley Chapter Party and Touchstone Awards

    Meetings, STC NorthBay Blog

    Join us to relax with fellow communicators, enjoy a buffet dinner, and celebrate excellence in the profession.

    Every year Touchstone, the Northern California Technical Communication Competition, receives many fine entries. We send the best ones to the STC International Summit Awards competitions. We will announce this year’s winners and display their entries throughout the evening.

    During the evening we will also recognize and honor competition judges and Berkeley chapter volunteers for their contributions to the chapter and the profession.

    Our yearly raffle: Wow, do we have some great items for our raffle this year! Thanks to the generosity and support from these wonderful vendors in our professional community:

    * Adobe is providing a copy of Technical Communication Suite 3
    * Author-it is providing a full user license to Author-it
    * ComponentOne is providing a license for Doc-To-Help Enterprise
    * MadCap Software is providing a copy of Flare V6
    For menu and registration details, please go to http://www.stc-berkeley.org/MonthlyMeeting/january2011_annual_party/meeting_details.shtml.

    Our October 2010 Meeting: Publishing PDFs from DITA

    Authoring applications, Meetings, STC NorthBay Blog,

    At our last meeting, Scott Prentice, chapter webmaster and president of Leximation, Inc., presented a concise summary of the motivations and issues involved in using the Darwin Information Typing Architecture to produce PDFs. Why use DITA at all? By using XML to author in a topic-oriented structure, DITA lets you rearrange topics and reuse them easily, depending on the deliverables (paper? PDA? online help?) you want from the same source material.

    Isn’t this a wonderful thing? Yes, it can certainly be, depending on the nature and size of the enterprise and the amount and different types of content required–but it is not for everyone, and you had better choose your approach carefully from the start.

    The great value that Scott provided in our online session was in detailing the various options. How much “manual” control to do you need (and have the technical resources to support)? How much built-in support do you need (and have the budget for)? What is the volume of your output and projection for future need, and how many “seats” do you need licenses for? These are just a few of the questions you must ask before heading down the DITA direction, because what looks like a simpler, more affordable approach at first could turn out to be an expensive, painful trap.

    For a concise listing of the products, prices, and particulars of a variety of commercial DITA applications, you can’t do much better than review the brief summary of DITA issues that Scott has provided. Read it and be wise.