Posted on by TC Camp Staff

Session 2 Summary – 26 January 2013

Notes from all sessions were shared at the end of the day in the final Summary Session. Notes from those scribes who sent them in have been posted here.

Challenges of using standards to support content development, consumption, and interchange. Includes tools, vendors, services, committees, when and how to choose, government regulations, etc.

  • S1000D
  • economize, rationalize, increase quality
  • resistance to struct authoring: get buy-in from writers; express ROI
  • capture metrics: link rot, typos, accuracy
  • reasons to adopt a standard: interchange, access to library of tools and techniques, user community
  • objection: “but our content is special”
  • 85% of the problems are the same–most problems are well-known
  • as a consultant, “accept” that it is special but offer as a starting point
  • tech writers don’t have some foundational concepts
  • “you go to LA, everyone has a screenplay, you come to Silicon Valley, everyone has an app”
    1. costs of inefficiency are often hidden
    2. people focus on bad experiences to the exclusion of future possibilities
    3. writerly types don’t like losing creativity
  • standards help us serve customers better: reuse, interchange (localization)
  • XML is a recommendation, not a standard
  • magma: minimal architecture for generic …
  • when is it appropriate to use a standard?
  • standard as a path to follow or a convention vs. as defined by a standards body adoption of a standard is a long path, not an augmentation
  • standards don’t help if your content is bad
  • convert legacy content, or make a break?
  • garbage in garbage out applies to standards also–and you can still be compliant
  • manage expectations with mgmt., users, customers
  • start with requirements–have to be able to articulate what you are trying to accomplish
  • big benefit of standards is to defer tools decisions until requirements are clear markup is data centric, tools are peripheral
  • when you use standards, you own your content; when you use proprietary tools, the vendor does as a consultant you are the expert, but use issue-centric conversation–build a business case
  • failure is blamed on consultants or standards exchange

How to work with offshore vendors and/or globally distributed project teams, collaboration across global teams, collaborative writing in distributed teams, etc.

This session offered a lot of anectdotal experiences from the participants. The moderator began the session by stating that there is a big cultural misunderstanding between the East and West, and that when dealing with vendors from Asia or India, you cannot make the same assuptions that you would  make if you were dealing with vendors from the US or Europe. In the Indian language, there is no word for “no” and if you ask for something, you will either get “yes” or a made-up story, or silence, but never “no” or “I don’t know.” It is also rare for people from India to ask clarifying questions because it’s considered rude to not just do exactly as they were told.
Sometimes working with global teams has benefits, such as the ability to timeshift the work, but it can also be frustrating because of communication/cultural issues. Here are a few tips that partcipants have tried in order to help alleviate these frustrations:
  • Use webex, videoconferencing, IM, and email frequently, to increase the amount of communication that occurs.
  • Get feedback about how the call/webex went, perhaps not immediately, but a day or two later to give people time to gather their thoughts and respond
  • Become friends on Facebook with some of your global colleagues, to help learn about them as individuals
  • Read books such as “Speaking of India: Bridging the Communications Gap when Working with Indians”
  • Meet face-to-face, either by going to your colleagues’ location or by having one of more of your colleagues come here
  • Interact with people who are local, but are from the country in which your colleagues reside
  • Have the right attitude and don’t place blame; try providing constructive criticism in a 1:1 situation rather than in a group
  • Encourage people to ask questions; start small and praise even the most minor sorts of questions (this applies more to places like India and Japan, and not so much to places like France and Israel)
  • When working on collaborative doc projects, set up clear ownership for diffferent parts of the document
  • Use wikis with outlines, schedules, and places for peer reiews
  • Take a class on working collaboratively, such as those offered by Joanne Hackos

What is the most efficient way to teach a traditional writer how to write topic-based content?

Scribe: Michael Belef

These notes are rough and incomplete. Our session was more about questions that students and writers had about learning topic-based writing, not how to teach it.  Alas, since Mike was the designated scribe and also the lone writer with structured experience. His notes below are not complete as he tried to answer many questions.

Participants and Experience:

  1. Bio Tech writer. Uses FrameMaker, uses context sensitive help, Started as software builder. The company outsourced the software teams so she transferred to tech writing.
  2. Tech writer since 1982, software company. No one wrote user docs. Later, got tech writing certificate at De Anza. Used a Texas instruments T-1000.
  3. One writer: 7 years at Medical instruments, three years in aerospace, 13 years in computer industry, Learned to use tools on the job. Sun workstations, PCs, Macs, many tools over the years.
  4. Three Students – interested in all aspects of tech writing, tools, how to learn tools and craft.
  5. Various levels of experience but none have structured authoring experience.

We discussed content tagging versus tagging for format.

Start writing from the perspective of chunking.

Keep topics small a couple paragraphs.

You can re-use, share info across departments, like marketing and training.

One writer explained that the developers create a hook file which the writer creates content for so it will display at that hook.

Have a mentor who can also teach. If you have an editor well versed in structure, the editor can really help writers grasp structure. I got my best training from my editor. The editor can focus more on content planning and helping the writer stick to the rules, while writers learn the tools and work with subject matter experts.

What programs should we focus on learning?  Well it depends on what you company or customer will use… oXygen Author, FrameMaker, XMetaL, others.

See the book DITA Best Practices, the author, Laura Bellamy is here today.

Mike: I think you have to just get hands on tools to learn it…. (Vendors at TC camp could help advertise their business by helping students and writers learn to use their authoring tools. Post the docs online so students can point to it and discuss it in class later.)

Mike also suggests that some of the solution providers here today, help mentor people who don’t have structured experience, show them what you do. This can help sell your expertise, demonstrate your business services.

Forms- and Wizard-based Authoring

currently unavailable

Visual presentations that are not text

  • Goal is to communicate
  • Need to consider pictures – Easy to grasp/retain info
    • Charts
    • Diagrams
    • Flowcharts
    • Tables
  • Requirement Analysis
  • Easy to spot gaps (flowcharts/diagrams)
  • Videos
    • screencasts for help with/without audio/captions
    • how-to/repair videos
  • How can we improve visual communication?
    • create portfolio
    • sample docs
    • magazine clippings
  • book recommendation: Edward Tufte books, Indi Young “Mental Models”